@mmerterden/multi-agent-pipeline 12.3.0 → 12.4.0

package/CHANGELOG.md

@@ -14,6 +14,38 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [12.4.0] - 2026-07-23
+
+User-defined routines: manage your own recurring, project-specific jobs as
+first-class `/multi-agent` commands.
+
+### Added
+
+- **`/multi-agent:save`** turns a recurring job into a reusable
+  `/multi-agent:<name>` command. It leads with the work actually executed in
+  the current session (distilling repeatable jobs from what was just done),
+  then adds named procedures found in `~/.claude/CLAUDE.md`, and offers them in
+  a multi-select picker: pick one, pick several to combine into one routine
+  (steps concatenated in order), or describe a new one via free text.
+- **`/multi-agent:routines`** lists saved routines with what each does, in
+  `outputLanguage`. **`/multi-agent:forget`** removes one (guarded: never
+  touches a shipped command).
+- Backed by `routine-registry.mjs` (add/list/remove/get; name validation,
+  collision + shipped-command guards, atomic prefs write). Saved routines are
+  `local-only: true` command dirs + a `prefs.global.routines` registry entry:
+  preserved across `/multi-agent:update` by the install snapshot/restore,
+  rejected from the public repo by the sync backstops, and never counted in the
+  command inventory.
+- Registered in `/multi-agent:help` (EN + TR "Routines" section with a dynamic
+  listing of saved routines).
+
+### Changed
+
+- Command inventory 38 -> 41 (`save`, `routines`, `forget`); contract, both sync
+  docs, help EN/TR, and the count smokes updated; 3 Copilot twins added.
+- prefs schema `global.routines` + `schemaVersion` 2.4.0; new
+  `prefs-2.3.0-to-2.4.0.mjs` migration (idempotent, adds `routines: []`).
+
 ## [12.3.0] - 2026-07-23
 
 `/multi-agent:analysis` overhaul: the feature-spec doc is now a development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.3.0",
+  "version": "12.4.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/forget/SKILL.md

@@ -0,0 +1,29 @@
+---
+description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms."
+description-tr: "Kaydedilmiş bir /multi-agent rutinini (/multi-agent:save ile oluşturulan) siler: local-only komutunu ve registry kaydını kaldırır. Hangisini soracak ve onay alacak."
+argument-hint: "[name]  -  routine to remove; asked if omitted"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# multi-agent forget  -  Remove a Routine
+
+Delete a routine the user saved via `/multi-agent:save`. Backed by `$HOME/.claude/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. **Resolve which routine.** If `$ARGUMENTS` names one, use it. Otherwise run `node "$HOME/.claude/scripts/routine-registry.mjs" list --json`, and `AskUserQuestion` (in `outputLanguage`) with one option per saved routine. No routines -> report there is nothing to forget and stop.
+
+2. **Confirm.** `AskUserQuestion` (in `outputLanguage`): "Remove `/multi-agent:<name>`? This deletes the routine command and its registry entry." Options: `{ label: "Remove", description: "Delete this routine" }`, `{ label: "Cancel", description: "Keep it" }`. Anything but Remove -> stop.
+
+3. **Remove:**
+   ```bash
+   node "$HOME/.claude/scripts/routine-registry.mjs" remove --name "<name>"
+   ```
+   The backend guards against removing a shipped command (it only deletes a dir that is BOTH registered AND `local-only: true`).
+
+4. **Report** (in `outputLanguage`): the routine is removed; note that its `/multi-agent:<name>` entry clears from autocomplete on the next session reload.
+
+## Notes
+
+- Only user-saved routines can be forgotten; shipped `/multi-agent:*` commands are refused by the backend.
+- To see what you can forget, run `/multi-agent:routines`.

package/pipeline/commands/multi-agent/help/SKILL.md

@@ -131,6 +131,15 @@ Setup & Maintenance:
 
 ------------------------------------------------------------
 
+Routines (your own reusable jobs):
+
+  /multi-agent:save [name]    Save a recurring job as a reusable /multi-agent:<name> command
+  /multi-agent:routines       List your saved routines and what each does
+  /multi-agent:forget [name]  Remove a saved routine
+<!-- ROUTINES_DYNAMIC: after printing the static lines above, read prefs.global.routines; if non-empty, append one indented line per routine "  /multi-agent:<name>   <description>" under a "Your saved routines:" subheading, in outputLanguage. If empty, print "  (none yet - use /multi-agent:save)". -->
+
+------------------------------------------------------------
+
 Interactive Launchers:
 
   /multi-agent:jira           List MY open Jira issues → pick → branch → mode → go
@@ -345,6 +354,15 @@ Setup & Maintenance:
 
 ------------------------------------------------------------
 
+Rutinler (kendi tekrar eden işlerin):
+
+  /multi-agent:save [ad]          Sık yaptığın bir işi yeniden kullanılabilir /multi-agent:<ad> komutu olarak kaydet
+  /multi-agent:routines           Kayıtlı rutinlerini ve ne yaptıklarını listele
+  /multi-agent:forget [ad]        Kayıtlı bir rutini kaldır
+<!-- ROUTINES_DYNAMIC: yukarıdaki statik satırlardan sonra prefs.global.routines'i oku; boş değilse her rutin için "  /multi-agent:<ad>   <açıklama>" satırını "Kayıtlı rutinlerin:" alt başlığı altında ekle (outputLanguage). Boşsa "  (henüz yok - /multi-agent:save kullan)" yaz. -->
+
+------------------------------------------------------------
+
 İnteraktif Launcher'lar:
 
   /multi-agent:jira           BENİM açık Jira issue'larımı listele → seç → branch → mode → başla

package/pipeline/commands/multi-agent/routines/SKILL.md

@@ -0,0 +1,30 @@
+---
+description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage."
+description-tr: "Kaydettiğin /multi-agent rutinlerini (/multi-agent:save ile) listeler; her birinin ne yaptığını outputLanguage'e göre gösterir."
+argument-hint: ""
+allowed-tools: Bash, Read
+---
+
+# multi-agent routines  -  List Saved Routines
+
+Show every routine the user saved via `/multi-agent:save`. Backed by `$HOME/.claude/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. **Read the registry:**
+   ```bash
+   node "$HOME/.claude/scripts/routine-registry.mjs" list --json
+   ```
+
+2. **Render in `outputLanguage`.** Empty list -> tell the user there are no saved routines yet and that `/multi-agent:save` creates one. Otherwise print a compact table, one row per routine:
+
+   | Komut / Command | Ne yapar / What it does | Oluşturma / Created |
+   |---|---|---|
+   | `/multi-agent:<name>` | `<description>` | `<createdAt date>` |
+
+3. **Integrity note (optional).** If a registry entry has no matching `~/.claude/commands/multi-agent/<name>/` dir (or a local-only routine dir exists with no registry entry), flag it as `needs repair` so the user can re-save or `/multi-agent:forget` it. Never modify anything here - this command is read-only.
+
+## Notes
+
+- Read-only. To add a routine use `/multi-agent:save`; to remove one use `/multi-agent:forget <name>`.
+- Routines are local-only and never synced; this list reflects only the current machine.

package/pipeline/commands/multi-agent/save/SKILL.md

@@ -0,0 +1,46 @@
+---
+description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; it is stored local-only and never synced."
+description-tr: "Sık yaptığın bir işi yeniden kullanılabilir /multi-agent:<ad> komutu olarak kaydeder. Konuşmayı + CLAUDE.md'ni tarayıp aday rutinler önerir, sen seçip ad verirsin; local-only saklanır, asla sync edilmez."
+argument-hint: "[name]  -  optional command name; asked if omitted"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# multi-agent save  -  Save a Routine
+
+**Input**: $ARGUMENTS (optional routine name)
+
+Turn a recurring, project-specific procedure into a first-class `/multi-agent:<name>` command. The saved routine is a **local-only** command (`local-only: true`) plus a registry entry in `prefs.global.routines`; it is never synced to the public repo (the `/multi-agent:sync` backstops enforce this).
+
+Backed by `$HOME/.claude/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. **Distill candidates from what was just done (primary source).** The user usually runs `:save` right after performing a job they want to repeat, so FIRST review the recent session: group the tasks/steps actually executed this conversation into coherent, repeatable jobs. Each distinct job is a candidate - give it a suggested short name, a one-line summary, and the ordered steps it would replay. THEN add, as further candidates, any named end-to-end procedures in `$HOME/.claude/CLAUDE.md` (heading + trigger phrase + numbered steps, e.g. a "... kontrol et" procedure). If nothing repeatable is found in the session and CLAUDE.md has none, say so and offer the free-text path only.
+
+2. **Pick (multi-select) + optionally combine.** `AskUserQuestion` with `multiSelect: true` (in `outputLanguage`): one option per distilled candidate (label = suggested name, description = the one-line summary), PLUS an always-present `Other` free-text path to describe a brand-new routine by hand. Semantics:
+   - one candidate selected -> that becomes the routine;
+   - several selected -> **combine them into ONE routine**, concatenating their steps in the order shown (the routine replays them in sequence); ask for a single name for the combined routine;
+   - `Other` -> the user types the routine themselves.
+   Empty selection is not consent - re-ask.
+
+3. **Name the command.** Use `$ARGUMENTS` if given, else ask. Validate: lowercase `^[a-z0-9][a-z0-9-]*$`, <= 40 chars. `routine-registry.mjs add` rejects a name that collides with a shipped command or an existing routine; on rejection, ask for another name.
+
+4. **Write the routine body** to a temp file: the full procedure the routine should run every time. For a single candidate, embed its steps (when the source is a CLAUDE.md section, reference that section by name AND embed a faithful copy so the routine is self-contained). For a combined (multi-select) routine, concatenate the selected candidates' steps in the shown order under numbered phase headings. Keep the user's own wording; do not invent steps.
+
+5. **Save.** Run:
+   ```bash
+   node "$HOME/.claude/scripts/routine-registry.mjs" add \
+     --name "<name>" \
+     --description "<one-line summary>" \
+     --description-tr "<Turkish one-line summary>" \
+     --source "<CLAUDE.md section name | conversation | user>" \
+     --body-file "/tmp/routine-<name>.md"
+   ```
+
+6. **Report + offer to run.** Tell the user (in `outputLanguage`): the routine is saved and will appear as `/multi-agent:<name>` in autocomplete **after the next session reload** (a freshly written command is not hot-loaded this session). Then offer to run it now (you have the procedure in hand, so you can execute it immediately without waiting for the slash command to register).
+
+## Notes
+
+- Never write under a repo `pipeline/` tree; routines live only under `~/.claude`.
+- The routine file always carries `local-only: true` (the backend asserts this), so `/multi-agent:sync` and the install namespace-wipe both preserve it and keep it out of the public repo.
+- List saved routines with `/multi-agent:routines`; remove one with `/multi-agent:forget <name>`.

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -56,7 +56,7 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 38 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 41 sub-command skills)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -257,14 +257,14 @@ This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**38 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**41 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -6,14 +6,14 @@
 
 ---
 
-## 1. Command Inventory (38 commands)
+## 1. Command Inventory (41 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 Categories:
@@ -25,6 +25,7 @@ Categories:
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
+- **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
 
 > **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
 

package/pipeline/schemas/migrations/prefs-2.3.0-to-2.4.0.mjs

@@ -0,0 +1,32 @@
+/**
+ * prefs-2.3.0-to-2.4.0.mjs  -  preference schema upgrade 2.3.0 -> 2.4.0
+ *
+ * Adds the user-defined routine registry:
+ *   - global.routines  (v2.4.0)  -  array of {name, description, createdAt,
+ *                                   source, trigger?} indexing local-only
+ *                                   /multi-agent:<name> commands saved via
+ *                                   /multi-agent:save. Never synced (personal).
+ *
+ * Defaults to an empty array. Existing v2.3.0 prefs validate against the
+ * v2.4.0 schema without it, but the migrator initializes it so the routine
+ * commands can read/append without null-guards.
+ *
+ * Idempotent: safe on already-2.4.0 input. Non-destructive: preserves any
+ * user-saved routines.
+ *
+ * @param {object} data  -  parsed JSON content of the preferences file
+ * @returns {object}     -  same data with schemaVersion = "2.4.0"
+ */
+export default function migrate(data) {
+  const out = JSON.parse(JSON.stringify(data));
+
+  out.schemaVersion = "2.4.0";
+
+  if (!out.global) out.global = {};
+
+  if (!Array.isArray(out.global.routines)) {
+    out.global.routines = [];
+  }
+
+  return out;
+}

package/pipeline/schemas/prefs.schema.json

@@ -17,7 +17,8 @@
         "2.0.0",
         "2.1.0",
         "2.2.0",
-        "2.3.0"
+        "2.3.0",
+        "2.4.0"
       ],
       "description": "v2.0.0: pre-v3.7. v2.1.0: v3.7+ adds identities[].servicePatMap, platformIdentityRouting, recentGroups, recentBranches, serviceStatus, settings, expanded keychainMapping. v2.2.0: v6.0.0 formalizes v5.7 / v5.8 additions (reportChannels, reportContent with technicalAnalysis, wikiScope, autopilotReportTimeoutSeconds) that had been running as 2.1.0 sub-migrations without a proper version bump."
     },
@@ -273,6 +274,40 @@
             "maxItems": 10
           }
         },
+        "routines": {
+          "type": "array",
+          "description": "v2.4.0+. User-defined routines saved via /multi-agent:save. Each entry indexes a local-only /multi-agent:<name> command dir under ~/.claude/commands/multi-agent/. Never synced (personal). Managed by routine-registry.mjs.",
+          "maxItems": 100,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "description"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "maxLength": 40,
+                "description": "Routine command name; invocable as /multi-agent:<name>."
+              },
+              "description": {
+                "type": "string",
+                "description": "One-line summary shown by /multi-agent:routines and :help."
+              },
+              "createdAt": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "source": {
+                "type": "string",
+                "description": "Where the routine came from, e.g. a CLAUDE.md section name or 'user'."
+              },
+              "trigger": {
+                "type": ["string", "null"],
+                "description": "Optional natural-language trigger phrase the routine captures."
+              }
+            }
+          }
+        },
         "recentGroups": {
           "type": "array",
           "description": "v2.1.0+. LRU of multi-repo selection groups. Each group is a set of repo paths chosen together for multi-repo tasks. Max 10.",

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -1,19 +1,19 @@
 .claude/.pipeline-version	1
 .claude/CLAUDE.md	1
 .claude/agents	8
-.claude/commands	44
+.claude/commands	47
 .claude/lib	27
 .claude/multi-agent-preferences.json	1
 .claude/multi-agent-refs	51
 .claude/rules	12
-.claude/schemas	23
-.claude/scripts	195
+.claude/schemas	24
+.claude/scripts	197
 .claude/settings.json	1
 .claude/skills	428
 .copilot/.pipeline-version	1
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	27
-.copilot/schemas	23
-.copilot/scripts	195
-.copilot/skills	467
+.copilot/schemas	24
+.copilot/scripts	197
+.copilot/skills	470

package/pipeline/scripts/migrate-prefs.mjs

@@ -18,7 +18,7 @@ const DEFAULT_FILE = path.join(os.homedir(), ".claude", "multi-agent-preferences
 
 // Single source of truth for the migration target version. Referenced by the
 // migrate() bump chain AND every user-facing message, so they cannot drift.
-const TARGET_VERSION = "2.3.0";
+const TARGET_VERSION = "2.4.0";
 
 const USAGE = "Usage: migrate-prefs.mjs [--dry-run] [--file <path>]";
 
@@ -164,6 +164,9 @@ function migrate(prefs) {
   const TARGET = TARGET_VERSION;
   if (out.schemaVersion === TARGET) {
     // already on target  -  skip version bump, but still run sub-migrations below
+  } else if (out.schemaVersion === "2.3.0") {
+    out.schemaVersion = TARGET;
+    changes.push(`schemaVersion: 2.3.0 → ${TARGET}`);
   } else if (out.schemaVersion === "2.2.0") {
     out.schemaVersion = TARGET;
     changes.push(`schemaVersion: 2.2.0 → ${TARGET}`);
@@ -241,6 +244,10 @@ function migrate(prefs) {
     out.global.accounts = [];
     changes.push("added empty accounts (v7.4.0 per-account host overrides)");
   }
+  if (!Array.isArray(out.global.routines)) {
+    out.global.routines = [];
+    changes.push("added empty routines (v2.4.0 user-defined /multi-agent:save routines)");
+  }
   if (!out.global.serviceStatus) {
     out.global.serviceStatus = {};
     changes.push("added empty serviceStatus");

package/pipeline/scripts/routine-registry.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// routine-registry.mjs  -  backend for the user-defined routine commands
+// (/multi-agent:save, :routines, :forget).
+//
+// A "routine" is a saved, reusable procedure the user binds to its own
+// /multi-agent:<name> slash command. Each routine is TWO artifacts:
+//   1. a local-only command dir  ~/.claude/commands/multi-agent/<name>/SKILL.md
+//      (frontmatter `local-only: true` -> the installer preserves it across
+//       updates and /multi-agent:sync refuses to leak it into the public repo)
+//   2. a registry entry in       ~/.claude/multi-agent-preferences.json
+//      at global.routines[]  (name, description, createdAt, source)
+//
+// This tool is the mechanical half; the save/routines/forget SKILLs drive the
+// UX (candidate discovery, pickers, confirmation) and call these subcommands.
+//
+// Zero deps. Never writes under a repo `pipeline/` tree; only ever under
+// <home>/.claude/. Refuses to touch a shipped (non-local-only) command dir.
+//
+// Usage:
+//   node routine-registry.mjs list [--json] [--home <dir>]
+//   node routine-registry.mjs get    --name <n> [--home <dir>]
+//   node routine-registry.mjs add     --name <n> --description <d>
+//        [--description-tr <t>] [--argument-hint <h>] --source <s> --body-file <f> [--home <dir>]
+//   node routine-registry.mjs remove  --name <n> [--home <dir>]
+//
+// Exit: 0 ok, 1 error (validation / collision / not-found), 64 usage.
+
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  renameSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_NAME = 40;
+const MAX_ROUTINES = 100;
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        out[key] = true;
+      } else {
+        out[key] = next;
+        i++;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function fail(msg) {
+  console.error(`routine-registry: ${msg}`);
+  process.exit(1);
+}
+
+function homeDir(args) {
+  return args.home || process.env.HOME || process.env.USERPROFILE || "";
+}
+function prefsPath(home) {
+  return join(home, ".claude", "multi-agent-preferences.json");
+}
+function routineDir(home, name) {
+  return join(home, ".claude", "commands", "multi-agent", name);
+}
+
+function readPrefs(home) {
+  const p = prefsPath(home);
+  if (!existsSync(p)) return { global: {} };
+  try {
+    const prefs = JSON.parse(readFileSync(p, "utf-8"));
+    if (!prefs.global) prefs.global = {};
+    return prefs;
+  } catch {
+    fail(`could not parse ${p}`);
+  }
+}
+
+function writePrefs(home, prefs) {
+  const p = prefsPath(home);
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp.${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(prefs, null, 2)}\n`);
+  renameSync(tmp, p);
+}
+
+function getRoutines(prefs) {
+  return Array.isArray(prefs.global.routines) ? prefs.global.routines : [];
+}
+
+// A dir is a shipped (non-routine) command when it exists and its SKILL.md is
+// NOT marked local-only. Those must never be overwritten or removed.
+function isLocalOnlyDir(dir) {
+  const skill = join(dir, "SKILL.md");
+  if (!existsSync(skill)) return false;
+  return /^local-only:\s*true\s*$/m.test(readFileSync(skill, "utf-8"));
+}
+
+function cmdList(home, json) {
+  const routines = getRoutines(readPrefs(home));
+  if (json) {
+    process.stdout.write(`${JSON.stringify(routines, null, 2)}\n`);
+    return;
+  }
+  if (routines.length === 0) {
+    console.log("(no routines saved)");
+    return;
+  }
+  for (const r of routines) {
+    console.log(`${r.name}\t${r.description || ""}\t${r.createdAt || ""}`);
+  }
+}
+
+function cmdGet(home, name) {
+  const r = getRoutines(readPrefs(home)).find((x) => x.name === name);
+  if (!r) fail(`no routine named "${name}"`);
+  process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+}
+
+function buildSkill(args) {
+  const desc = args.description;
+  const descTr = args["description-tr"];
+  const hint = args["argument-hint"] || "[optional args]";
+  const body = readFileSync(args["body-file"], "utf-8").trimEnd();
+  const fm = [
+    "---",
+    `description: ${JSON.stringify(desc)}`,
+    descTr ? `description-tr: ${JSON.stringify(descTr)}` : null,
+    `argument-hint: ${JSON.stringify(hint)}`,
+    "allowed-tools: Skill, Bash, Read, Edit, Write, AskUserQuestion",
+    "local-only: true",
+    "---",
+  ].filter(Boolean);
+  return `${fm.join("\n")}\n\n# multi-agent ${args.name}  -  saved routine\n\n**Input**: $ARGUMENTS\n\n${body}\n`;
+}
+
+function cmdAdd(home, args) {
+  const name = args.name;
+  if (!name || !NAME_RE.test(name) || name.length > MAX_NAME) {
+    fail(`invalid --name (need ${NAME_RE} , <= ${MAX_NAME} chars): ${name}`);
+  }
+  if (!args.description) fail("--description is required");
+  if (!args["body-file"] || !existsSync(args["body-file"])) {
+    fail("--body-file is required and must exist");
+  }
+  const dir = routineDir(home, name);
+  // Collision: an existing non-local-only dir is a shipped command - never touch.
+  if (existsSync(dir) && !isLocalOnlyDir(dir)) {
+    fail(`"${name}" collides with a shipped command; pick another name`);
+  }
+  const prefs = readPrefs(home);
+  const routines = getRoutines(prefs);
+  if (routines.some((r) => r.name === name)) {
+    fail(`a routine named "${name}" already exists; forget it first or pick another name`);
+  }
+  if (routines.length >= MAX_ROUTINES) fail(`routine cap (${MAX_ROUTINES}) reached`);
+
+  mkdirSync(dir, { recursive: true });
+  const skill = buildSkill(args);
+  // Safety: the generated file MUST be local-only so it never syncs to the repo.
+  if (!/^local-only:\s*true\s*$/m.test(skill)) fail("internal: generated SKILL missing local-only");
+  writeFileSync(join(dir, "SKILL.md"), skill);
+
+  routines.push({
+    name,
+    description: args.description,
+    createdAt: new Date().toISOString(),
+    source: args.source || "user",
+  });
+  prefs.global.routines = routines;
+  writePrefs(home, prefs);
+  console.log(`routine-registry: saved "${name}" -> ${join(dir, "SKILL.md")}`);
+  console.log("routine-registry: available as /multi-agent:" + name + " after a session reload");
+}
+
+function cmdRemove(home, name) {
+  if (!name) fail("--name is required");
+  const prefs = readPrefs(home);
+  const routines = getRoutines(prefs);
+  const idx = routines.findIndex((r) => r.name === name);
+  const dir = routineDir(home, name);
+  // Guard: only remove a dir that is BOTH registered AND local-only.
+  if (existsSync(dir) && !isLocalOnlyDir(dir)) {
+    fail(`"${name}" is a shipped command, not a routine; refusing to remove`);
+  }
+  if (idx < 0 && !existsSync(dir)) fail(`no routine named "${name}"`);
+  if (existsSync(dir) && isLocalOnlyDir(dir)) rmSync(dir, { recursive: true, force: true });
+  if (idx >= 0) {
+    routines.splice(idx, 1);
+    prefs.global.routines = routines;
+    writePrefs(home, prefs);
+  }
+  console.log(`routine-registry: removed "${name}" (clears from autocomplete on next session reload)`);
+}
+
+function main() {
+  const [, , sub, ...rest] = process.argv;
+  const args = parseArgs(rest);
+  const home = homeDir(args);
+  if (!home) fail("cannot resolve home dir");
+  switch (sub) {
+    case "list":
+      return cmdList(home, Boolean(args.json));
+    case "get":
+      return cmdGet(home, args.name);
+    case "add":
+      return cmdAdd(home, args);
+    case "remove":
+      return cmdRemove(home, args.name);
+    default:
+      console.error("usage: routine-registry.mjs <list|get|add|remove> [flags]  (see header)");
+      process.exit(64);
+  }
+}
+
+main();

package/pipeline/scripts/smoke-generate-issue.sh

@@ -91,11 +91,11 @@ echo ""
 echo "→ 8. registration + count consistency (36)"
 grep -Fq '| `create-jira ' "$DISPATCHER" && pass "dispatcher routing: create-jira" || fail "dispatcher routing missing: generate"
 grep -Fq "create-jira/SKILL.md" "$DISPATCHER" && pass "dispatcher loading row" || fail "dispatcher loading row missing"
-grep -Fq "## 1. Command Inventory (38 commands)" "$CONTRACT" && pass "contract count = 38" || fail "contract count wrong"
+grep -Fq "## 1. Command Inventory (41 commands)" "$CONTRACT" && pass "contract count = 41" || fail "contract count wrong"
 grep -Eq '(^|[ ,])create-jira([ ,]|$)' "$CONTRACT" && pass "contract list has create-jira" || fail "contract list missing generate"
-grep -Fq "**38 commands are synced**" "$SYNC" && pass "sync count = 38" || fail "sync count wrong"
+grep -Fq "**41 commands are synced**" "$SYNC" && pass "sync count = 41" || fail "sync count wrong"
 SYNC_SKILL="$ROOT/pipeline/skills/shared/core/multi-agent-sync/SKILL.md"
-grep -Fq "**38 commands are synced**" "$SYNC_SKILL" && pass "sync SKILL count = 38" || fail "sync SKILL count wrong (Copilot parity)"
+grep -Fq "**41 commands are synced**" "$SYNC_SKILL" && pass "sync SKILL count = 41" || fail "sync SKILL count wrong (Copilot parity)"
 grep -Fq "create-jira" "$ROOT/pipeline/skills/shared/core/multi-agent-help/SKILL.md" && pass "help SKILL lists create-jira" || fail "help SKILL missing create-jira (Copilot parity)"
 grep -c "multi-agent:create-jira" "$HELP" | awk '{exit !($1>=2)}' && pass "help.md has EN + TR entries" || fail "help.md entries incomplete"
 # no stale split-command references anywhere in the synced surfaces

package/pipeline/scripts/smoke-migrate-state.sh

@@ -75,12 +75,12 @@ else
   fail "unknown flag did not exit 1"
 fi
 
-# Test 7  -  type auto-detection works
+# Test 7  -  type auto-detection works (feed a doc already at the latest version)
 cat > "$TMPDIR/multi-agent-preferences.json" <<'EOF'
-{"schemaVersion":"2.3.0","global":{"identities":[],"keychainMapping":{},"recentAccounts":[],"accounts":[]},"projects":{}}
+{"schemaVersion":"2.4.0","global":{"identities":[],"keychainMapping":{},"recentAccounts":[],"accounts":[],"routines":[]},"projects":{}}
 EOF
 OUT=$(node "$RUNNER" "$TMPDIR/multi-agent-preferences.json" 2>&1)
-if echo "$OUT" | grep -q "already at schemaVersion 2.3.0"; then
+if echo "$OUT" | grep -q "already at schemaVersion 2.4.0"; then
   pass "prefs type auto-detected from filename"
 else
   fail "prefs auto-detection failed (got: $OUT)"

package/pipeline/scripts/smoke-pref-migration.sh

@@ -64,7 +64,7 @@ F1=$(run_fixture "f1-v2.0.0-legacy" '{
   },
   "projects": {}
 }')
-assert_json_has "f1" "$F1" ".schemaVersion" "2.3.0"
+assert_json_has "f1" "$F1" ".schemaVersion" "2.4.0"
 assert_json_has "f1" "$F1" ".global.identities" "array:1"
 assert_json_has "f1" "$F1" ".global.gitIdentities" "undefined"
 assert_json_has "f1" "$F1" ".global.settings" "object:8"
@@ -73,6 +73,7 @@ assert_json_has "f1" "$F1" ".global.platformIdentityRouting" "object:0"
 assert_json_has "f1" "$F1" ".global.recentGroups" "array:0"
 assert_json_has "f1" "$F1" ".global.recentAccounts" "array:0"
 assert_json_has "f1" "$F1" ".global.accounts" "array:0"
+assert_json_has "f1" "$F1" ".global.routines" "array:0"
 
 echo ""
 echo "→ Fixture 2: no schemaVersion (pre-2.0.0 fossil)"
@@ -80,15 +81,15 @@ F2=$(run_fixture "f2-no-version" '{
   "global": {"gitIdentities": []},
   "projects": {}
 }')
-assert_json_has "f2" "$F2" ".schemaVersion" "2.3.0"
+assert_json_has "f2" "$F2" ".schemaVersion" "2.4.0"
 assert_json_has "f2" "$F2" ".global.identities" "array:0"
 
 echo ""
-echo "→ Fixture 3: v2.3.0 already (no-op)"
-F3_FILE="$TMP/f3-v2.3.0.json"
+echo "→ Fixture 3: v2.4.0 already (no-op)"
+F3_FILE="$TMP/f3-v2.4.0.json"
 cat > "$F3_FILE" <<'EOF'
 {
-  "schemaVersion": "2.3.0",
+  "schemaVersion": "2.4.0",
   "global": {
     "identities": [],
     "keychainMapping": {
@@ -117,7 +118,8 @@ cat > "$F3_FILE" <<'EOF'
     "wikiScope": ["main", "ios", "screenshots", "index"],
     "autopilotReportTimeoutSeconds": 1800,
     "recentAccounts": [],
-    "accounts": []
+    "accounts": [],
+    "routines": []
   },
   "projects": {}
 }

package/pipeline/scripts/smoke-review-readiness.sh

@@ -66,7 +66,7 @@ grep -Fq '| `review-jira ' "$DISPATCHER" && pass "dispatcher desc: review-jira"
 grep -Fq '| `review-issue ' "$DISPATCHER" && pass "dispatcher desc: review-issue" || fail "dispatcher desc missing review-issue"
 grep -Fq "review-jira/SKILL.md" "$DISPATCHER" && pass "dispatcher routing: review-jira" || fail "dispatcher routing missing review-jira"
 grep -Fq "review-issue/SKILL.md" "$DISPATCHER" && pass "dispatcher routing: review-issue" || fail "dispatcher routing missing review-issue"
-grep -Fq "## 1. Command Inventory (38 commands)" "$CONTRACT" && pass "contract count = 38" || fail "contract count wrong"
+grep -Fq "## 1. Command Inventory (41 commands)" "$CONTRACT" && pass "contract count = 41" || fail "contract count wrong"
 grep -Eq '(^|[ ,])review-jira([ ,]|$)' "$CONTRACT" && pass "contract inventory has review-jira" || fail "contract missing review-jira"
 grep -Eq '(^|[ ,])review-issue([ ,]|$)' "$CONTRACT" && pass "contract inventory has review-issue" || fail "contract missing review-issue"
 grep -Fq "multi-agent:review-jira" "$HELP" && pass "help lists review-jira" || fail "help missing review-jira"

package/pipeline/scripts/smoke-routines.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# smoke-routines.sh  -  contract for routine-registry.mjs, the backend of the
+# user-defined routine commands (/multi-agent:save, :routines, :forget).
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+RR="$SCRIPT_DIR/routine-registry.mjs"
+
+PASS=0
+FAIL=0
+record_pass() { PASS=$((PASS + 1)); printf '  \342\234\223 %s\n' "$1"; }
+record_fail() { FAIL=$((FAIL + 1)); printf '  \342\234\227 %s\n' "$1"; }
+
+printf '\342\206\222 smoke-routines: routine-registry backend contract\n'
+
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/routines.XXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+H="$tmp/home"
+mkdir -p "$H/.claude/commands/multi-agent"
+printf '{"global":{}}\n' > "$H/.claude/multi-agent-preferences.json"
+printf 'Run steps 1-6 of the checkin service migration.\n' > "$tmp/body.md"
+
+# 1. add -> writes a local-only command dir + registry entry
+node "$RR" add --name checkin-services --description "Checkin servis kontrolu" \
+  --source "CLAUDE.md" --body-file "$tmp/body.md" --home "$H" >/dev/null 2>&1
+skill="$H/.claude/commands/multi-agent/checkin-services/SKILL.md"
+if [ -f "$skill" ] && grep -qx "local-only: true" "$skill"; then
+  record_pass "add writes a local-only command SKILL.md"
+else
+  record_fail "add did not write a local-only routine command"
+fi
+if node "$RR" list --json --home "$H" | grep -q '"name": "checkin-services"'; then
+  record_pass "registry records the routine"
+else
+  record_fail "registry missing the routine"
+fi
+
+# 2. add is name-collision safe (same name rejected)
+node "$RR" add --name checkin-services --description x --source y --body-file "$tmp/body.md" --home "$H" >/dev/null 2>&1
+[ "$?" -eq 1 ] && record_pass "duplicate name rejected" || record_fail "duplicate name should reject"
+
+# 3. invalid name rejected
+node "$RR" add --name "Bad Name" --description x --source y --body-file "$tmp/body.md" --home "$H" >/dev/null 2>&1
+[ "$?" -eq 1 ] && record_pass "invalid name rejected" || record_fail "invalid name should reject"
+
+# 4. shipped-command guard: never remove a non-local-only command
+mkdir -p "$H/.claude/commands/multi-agent/status"
+printf -- '---\ndescription: "shipped"\n---\nbody\n' > "$H/.claude/commands/multi-agent/status/SKILL.md"
+node "$RR" remove --name status --home "$H" >/dev/null 2>&1
+if [ "$?" -eq 1 ] && [ -d "$H/.claude/commands/multi-agent/status" ]; then
+  record_pass "refuses to remove a shipped command"
+else
+  record_fail "shipped command must be protected"
+fi
+
+# 5. sync backstop proxy: the generated routine carries local-only:true, which is
+# exactly what sync/SKILL.md greps to keep it out of the public repo.
+if grep -qx "local-only: true" "$skill"; then
+  record_pass "routine is sync-excluded (local-only marker present)"
+else
+  record_fail "routine missing local-only marker (would leak on sync)"
+fi
+
+# 6. remove -> deletes dir + registry entry
+node "$RR" remove --name checkin-services --home "$H" >/dev/null 2>&1
+if [ ! -d "$H/.claude/commands/multi-agent/checkin-services" ] \
+  && ! node "$RR" list --json --home "$H" | grep -q "checkin-services"; then
+  record_pass "remove deletes dir + registry entry"
+else
+  record_fail "remove left dir or registry entry behind"
+fi
+
+# 7. install preservation proxy: snapshotLocalOnlyWrappers keys on local-only:true.
+# Re-add, then confirm the marker survives a simulated namespace re-read.
+node "$RR" add --name my-routine --description d --source s --body-file "$tmp/body.md" --home "$H" >/dev/null 2>&1
+if grep -qx "local-only: true" "$H/.claude/commands/multi-agent/my-routine/SKILL.md"; then
+  record_pass "re-added routine keeps the install-preserving marker"
+else
+  record_fail "re-added routine lost its local-only marker"
+fi
+
+printf '\n\342\225\220\342\225\220 smoke-routines: %d passed, %d failed \342\225\220\342\225\220\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

package/pipeline/skills/shared/core/multi-agent-forget/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: multi-agent-forget
+language: en
+description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms."
+user-invocable: true
+argument-hint: "[name]"
+---
+
+# multi-agent-forget  -  Remove a Routine
+
+Delete a routine saved via `/multi-agent:save`. Backed by `$HOME/.copilot/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. Resolve which routine: from `$ARGUMENTS`, else `routine-registry.mjs list --json` + `AskUserQuestion` (in `outputLanguage`). None -> nothing to forget.
+2. Confirm via `AskUserQuestion`: "Remove /multi-agent:<name>?" (Remove / Cancel). Anything but Remove -> stop.
+3. `node "$HOME/.copilot/scripts/routine-registry.mjs" remove --name "<name>"` (backend refuses to remove a shipped command; only a registered `local-only: true` dir).
+4. Report removed; note the autocomplete entry clears on the next session reload.
+
+## Notes
+
+- Only user-saved routines can be forgotten. See `/multi-agent:routines` for the list.

package/pipeline/skills/shared/core/multi-agent-routines/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: multi-agent-routines
+language: en
+description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage."
+user-invocable: true
+---
+
+# multi-agent-routines  -  List Saved Routines
+
+Show every routine saved via `/multi-agent:save`. Read-only. Backed by `$HOME/.copilot/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. `node "$HOME/.copilot/scripts/routine-registry.mjs" list --json`
+2. Render in `outputLanguage`: empty -> say there are none yet and point to `/multi-agent:save`; otherwise a compact table of `/multi-agent:<name>` + description + created date.
+3. Flag any registry entry with no matching command dir (or vice versa) as `needs repair`; never modify anything.
+
+## Notes
+
+- Add with `/multi-agent:save`, remove with `/multi-agent:forget <name>`. Routines are local-only and never synced.

package/pipeline/skills/shared/core/multi-agent-save/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: multi-agent-save
+language: en
+description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; stored local-only, never synced."
+user-invocable: true
+argument-hint: "[name]"
+---
+
+# multi-agent-save  -  Save a Routine
+
+**Input**: $ARGUMENTS (optional routine name)
+
+Turn a recurring procedure into a reusable `/multi-agent:<name>` command. The routine is stored local-only (a `local-only: true` command + a `prefs.global.routines` entry) and is never synced. Backed by `$HOME/.copilot/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. Distill candidates from what was just done (primary): group the tasks executed this session into coherent, repeatable jobs (suggested name + one-line summary + ordered steps). Then add named end-to-end procedures from `$HOME/.claude/CLAUDE.md`.
+2. `AskUserQuestion` with `multiSelect: true` (in `outputLanguage`): one option per candidate + an always-present `Other` free-text. One selected -> that routine; several selected -> combine into ONE routine (steps concatenated in shown order, single name); `Other` -> user types it. Empty is not consent.
+3. Name the command (from `$ARGUMENTS` or ask); validate `^[a-z0-9][a-z0-9-]*$`, <= 40 chars; the backend rejects collisions.
+4. Write the full procedure body to a temp file (single candidate: embed its steps, reference the CLAUDE.md section by name when that is the source; combined: concatenate the selected candidates' steps in order under numbered phase headings). Do not invent steps.
+5. Save: `node "$HOME/.copilot/scripts/routine-registry.mjs" add --name "<name>" --description "<summary>" --source "<source>" --body-file "/tmp/routine-<name>.md"`.
+6. Report it is available as `/multi-agent:<name>` after a session reload; offer to run it now.
+
+## Notes
+
+- Never writes under a repo `pipeline/` tree; routines live only under the CLI home.
+- List with `/multi-agent:routines`; remove with `/multi-agent:forget <name>`.

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -29,7 +29,7 @@ Run all steps automatically:
 
 ```
 Step 1: DETECT      Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 38 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 41 sub-command skills)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
 Step 5: Commit      Commit + push all changed repos
@@ -136,14 +136,14 @@ When invoked with the `release` argument:
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**38 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**41 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 **NOT synced**: `refs/*`  -  Lazy-load references, Claude Code specific