@aiwg/cli 2026.10.1 → 2026.10.4

package/tools/agents/providers/cursor.mjs

@@ -27,6 +27,8 @@ try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs;
 import path from 'path';
 import { spawn } from 'child_process';
 import {
+  withRuleDeployment,
+  parseRuleActivation,
   ensureDir,
   listMdFiles,
   listMdFilesRecursive,
@@ -117,25 +119,20 @@ export function transformCommand(srcPath, content, opts) {
   return content;
 }
 
-/**
- * Transform rule content for Cursor — inject MDC frontmatter with the
- * activation mode mapping per ADR-2 (rule activation mode schema).
- *
- * Reads the source rule's `activation:` field (or defaults to alwaysApply
- * per ADR-2 §2 default-preservation) and emits the corresponding MDC
- * frontmatter fields:
- *   - alwaysApply (true): activation === 'alwaysApply' (default)
- *   - alwaysApply (false), no globs: activation === 'auto'
- *   - globs: activation === 'glob' + globs: '<pattern>'
- *   - alwaysApply (false), description: activation === 'manual'
- *
- * Per ADR-2 §5: until the live-Cursor smoke test gate is in CI, all rules
- * deploy with alwaysApply: true regardless of source `activation` value
- * (with a deploy-time warning when the source declared a non-alwaysApply
- * mode). The deploy-time warning is emitted by the deployer, not this
- * transform.
- */
+/** Compile the shared five-mode activation contract to native MDC. */
 export function transformRule(srcPath, content, opts) {
+  const parsed = parseRuleActivation(content);
+  if (!parsed.valid) throw new Error(`${srcPath}: ${parsed.diagnostics.map(d => d.message).join('; ')}`);
+  if (parsed.rule.tagged) {
+    const rule = parsed.rule;
+    // Bound/on-demand rules have no auto-selection description or glob hint.
+    const fields = rule.activation === 'paths'
+      ? `globs: ${JSON.stringify(rule.paths)}\nalwaysApply: false`
+      : rule.activation === 'summary'
+        ? `description: ${JSON.stringify(rule.summary)}\nalwaysApply: false`
+        : `alwaysApply: ${rule.activation === 'kernel'}`;
+    return `---\n${fields}\n---\n${parsed.body}`;
+  }
   // Detect proper YAML frontmatter — must close within the first 30 lines.
   // Files with `---` horizontal rules deeper in markdown content (like
   // RULES-INDEX.md) can have multiple `---` lines without being frontmatter;
@@ -451,6 +448,10 @@ export function getFileExtension(type) {
  * Orchestrates deployment of agents, commands, skills, and rules
  */
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath, transformRule }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,

package/tools/agents/providers/grok-build.mjs

@@ -216,7 +216,9 @@ function regularFiles(dir, prefix = '') {
 function matchesSkillSource(source, target) {
   try {
     const expected = regularFiles(source);
-    const actual = regularFiles(target).filter(name => name !== '.aiwg-managed');
+    // The marker and the per-skill ownership receipt are AIWG bookkeeping,
+    // not skill content, so neither makes a deployed skill look modified.
+    const actual = regularFiles(target).filter(name => name !== '.aiwg-managed' && name !== '.aiwg-manifest.json');
     if (JSON.stringify(expected) !== JSON.stringify(actual)) return false;
     return expected.every(relative => {
       if (relative.endsWith(path.sep)) return true;

package/tools/agents/providers/grokbot.mjs

@@ -1,5 +1,5 @@
 /**
- * Grok Bot provider (experimental).
+ * Grok Bot provider (stable).
  *
  * Discover-first project bridge + fail-closed user skill root.
  * Never targets `.cursor/**` or invents `~/.grokbot`.
@@ -127,21 +127,18 @@ export function deployRules() {
 }
 
 /**
- * Deploy skills only when AIWG_GROKBOT_SKILLS_DIR is configured.
+ * Deploy skills only at user scope with AIWG_GROKBOT_SKILLS_DIR configured.
  * Kernel → configured root; standard → index/discovery unless --copy-all
  * (then `<root>/.aiwg/skills`).
  */
 export function deploySkills(skillDirs, targetDir, opts = {}) {
-  const root = resolveGrokbotSkillsDir(opts.env || process.env);
-  if (!root) {
+  if (opts.userScope !== true && opts.scope !== 'user') {
     if (!opts.quiet) {
-      console.log(
-        `\n  Grok Bot: skipping native skill copy (${SKILLS_DIR_ENV} unset). ` +
-          'Skills remain available via aiwg discover / aiwg show.',
-      );
+      console.log('\n  Grok Bot: project bridge only; native skills require --scope user.');
     }
     return 0;
   }
+  const root = assertUserScopeConfigured(opts);
 
   if (root.includes(`${path.sep}.cursor${path.sep}`) || root.endsWith(`${path.sep}.cursor`) || root.includes('/.cursor/') || root.endsWith('/.cursor')) {
     throw new Error(
@@ -178,14 +175,14 @@ export async function postDeploy(targetDir, opts = {}) {
   }
   if (!opts.quiet) {
     const root = resolveGrokbotSkillsDir(opts.env || process.env);
-    if (root) {
+    if (root && (opts.userScope === true || opts.scope === 'user')) {
       console.log(
         'Grok Bot: after deploy, start a new agent chat or re-read skills. ' +
           'Live refresh is not claimed until product behavior is verified.',
       );
     } else {
       console.log(
-        `Grok Bot: project bridge only. Set ${SKILLS_DIR_ENV} for user-scope skill deploy.`,
+        `Grok Bot: project bridge only. Use --scope user with ${SKILLS_DIR_ENV} for native skills.`,
       );
     }
   }
@@ -197,7 +194,7 @@ export function getFileExtension() {
 
 /**
  * Assert user-scope is allowed. Called when the orchestrator is mirroring
- * to user scope or when opts.scope === 'user'.
+ * to user scope or when opts.userScope === true / opts.scope === 'user'.
  */
 export function assertUserScopeConfigured(opts = {}) {
   const root = resolveGrokbotSkillsDir(opts.env || process.env);
@@ -227,7 +224,9 @@ export async function deploy(opts = {}) {
     console.log(`Mode: ${mode}`);
     const root = resolveGrokbotSkillsDir(opts.env || process.env);
     console.log(
-      `Skills root: ${root || `(unset — set ${SKILLS_DIR_ENV} for user-scope writes)`}`,
+      (opts.userScope === true || scope === 'user')
+        ? `User skills root: ${root || `(unset — set ${SKILLS_DIR_ENV})`}`
+        : 'Skills: project bridge only (no native skill writes)',
     );
     if (opts.dryRun) console.log('Dry-run: no filesystem mutations');
   }

package/tools/agents/providers/hermes.mjs

@@ -24,9 +24,9 @@ import path from 'path';
 import os from 'os';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
-  listSkillDirs,
   deploySkillDir,
   deploySkillsWithKernelRouting,
   isKernelSkill,
@@ -193,8 +193,8 @@ export function mapModel(shorthand, modelCfg, modelsConfig) {
 /**
  * Generate a lean AGENTS.md for Hermes
  *
- * Hermes loads AGENTS.md on every turn — keep it under 1,000 characters
- * to preserve context budget on 12GB VRAM setups.
+ * Hermes reaches AGENTS.md through its startup pointer on every task. Reserve
+ * the 19,000-character budget for CRITICAL kernel bodies and the kernel index.
  * See: docs/integrations/hermes-quickstart.md (Part 3)
  */
 // Hermes context cap is 20K chars (head-tail truncated above). Hard limit
@@ -202,6 +202,23 @@ export function mapModel(shorthand, modelCfg, modelsConfig) {
 const HERMES_AGENTS_MD_HARD_CAP = 19_000;
 const HERMES_AGENTS_MD_SOFT_WARN = 15_000;
 
+/** Never truncate CRITICAL bodies. Report each contribution before promotion. */
+export function assertContextBudget(content, name = 'AGENTS.md', rules = []) {
+  if (content.length <= HERMES_AGENTS_MD_HARD_CAP) return;
+  const critical = rules.filter(rule => rule.tagged && rule.activation === 'kernel'
+    && String(rule.enforcement || '').trim().toLowerCase() === 'critical');
+  const sizes = critical.map(rule => ({ name: rule.name,
+    chars: `## Rule: ${rule.name}\n\n${rule.body.trim()}`.length }));
+  const total = sizes.reduce((sum, rule) => sum + rule.chars, 0) + Math.max(0, sizes.length - 1) * 2;
+  throw new Error(
+    `Hermes ${name} (${content.length} chars) exceeds hard cap of ${HERMES_AGENTS_MD_HARD_CAP}. ` +
+    `Hermes truncates above 20K. ` +
+    (total > HERMES_AGENTS_MD_HARD_CAP ? 'CRITICAL kernel set alone exceeds the cap. ' : 'Assembled context exceeds the cap; review wrappers and operator additions. ') +
+    `CRITICAL kernel total: ${total} chars (bodies and rule headings).\n` +
+    sizes.map(rule => `  ${rule.name}: ${rule.chars} chars`).join('\n')
+  );
+}
+
 /**
  * Top-7 CRITICAL rule directives, inlined into AGENTS.md for guaranteed
  * priming on every Hermes turn (#1318 / S7; skill-discovery added #1347).
@@ -298,41 +315,32 @@ surface as provider-agnostic tools when configured.
 **Artifacts** (project-required, .aiwg/ directory):
 - \`mcp_aiwg_artifact_read\` / \`mcp_aiwg_artifact_write\``;
 
+function mergeHermesContext(file, generated, kind) {
+  let existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  existing = existing.replace(/\n?<!-- AIWG:rule-startup:start -->[\s\S]*?<!-- AIWG:rule-startup:end -->\n?/g, '');
+  const start = `<!-- AIWG:hermes-${kind}:start -->`;
+  const end = `<!-- AIWG:hermes-${kind}:end -->`;
+  const managed = `${start}\n${generated}\n${end}`;
+  if (existing.includes(start)) return existing.slice(0, existing.indexOf(start)) + managed + existing.slice(existing.indexOf(end) + end.length);
+  if (kind === 'context' && existing.startsWith('# AIWG Integration') && existing.includes(HERMES_AGENTS_MD_FOOTER)) {
+    existing = existing.slice(existing.indexOf(HERMES_AGENTS_MD_FOOTER) + HERMES_AGENTS_MD_FOOTER.length);
+  } else if (kind === 'routing' && existing.includes(generated)) {
+    existing = existing.replace(generated, '');
+  }
+  return existing ? `${existing.trimEnd()}\n\n${managed}\n` : `<!-- aiwg-managed -->\n${managed}\n`;
+}
+
 export function generateAgentsMd(agentCount, skillCount, targetDir, opts) {
   const { dryRun } = opts;
 
+  // Startup is reserved for rule contracts. Workflow routing, artifact catalogs,
+  // and the optional MCP tool inventory duplicate discover/show and consume
+  // Hermes's finite per-turn context before the kernel is appended.
   const header = `# AIWG Integration
 
-AIWG connected through file-based deployment. Native Hermes skills are available
-at \`$HERMES_HOME/skills/\` (kernel) and \`$HERMES_HOME/skills/.aiwg/\` (standard).
-When unset, \`HERMES_HOME\` defaults to the platform-native Hermes home.
-Use \`aiwg discover\` and \`aiwg show <type> <name>\` for the on-demand catalog.
-The MCP sidecar (\`aiwg mcp serve\`) is optional.
-
-## Route to AIWG When
-
-- Structured artifacts needed (requirements, architecture, test plans, risk registers)
-- Multi-step workflows with phase gates or checkpoints
-- Template-driven output that persists across sessions
-
-Handle in Hermes directly: one-off questions, short tasks, conversation.
-
-## Memory Boundary
-
-When AIWG returns an artifact: store path + one-sentence summary in MEMORY.md.
-Do NOT copy artifact body text into memory. Reference, don't replicate.
-
-Use \`delegate_task(goal="...", context="...")\` for AIWG workflows.
-Child agents automatically exclude context files and memory.
-
-## Artifact Store (.aiwg/)
-
-Fetch on demand via \`mcp_aiwg_artifact_read\`:
-- \`requirements/\` — use cases, user stories
-- \`architecture/\` — SAD, ADRs
-- \`planning/\` — phase plans
-- \`testing/\` — test strategy
-- \`security/\` — threat models
+Skills: \`$HERMES_HOME/skills/\` (kernel), \`$HERMES_HOME/skills/.aiwg/\` (standard).
+Find: \`aiwg discover "rule <topic>" --type rule\`. Fetch: \`aiwg show rule <name>\`.
+MCP is optional; \`mcp_aiwg_rule_show\` exposes the same rule catalog.
 `;
 
   // On-demand tier (#1675): the MEDIUM/LOW rules not inlined above. Hermes has
@@ -340,18 +348,15 @@ Fetch on demand via \`mcp_aiwg_artifact_read\`:
   const onDemandSection = opts.srcRoot
     ? renderOnDemandRuleSection(listOnDemandRuleFiles(opts.srcRoot))
     : '';
-  const sections = [header, CRITICAL_RULE_DIRECTIVES];
+  const migrated = new Set((opts.ruleDelivery?.rules || []).filter(rule => rule.tagged).map(rule => rule.name));
+  const directives = CRITICAL_RULE_DIRECTIVES.split(/(?=^### Rule: )/m).filter(section => section.startsWith('### Rule: ') && !migrated.has(section.match(/^### Rule: ([^ \n]+)/)?.[1])).join('');
+  const sections = [header, directives];
   if (onDemandSection) sections.push(onDemandSection);
-  sections.push(HERMES_AGENTS_MD_FOOTER);
-  const output = sections.join('\n\n');
+  // The optional tool inventory is available on demand through the CLI.
   const destPath = path.join(targetDir, 'AGENTS.md');
+  const output = mergeHermesContext(destPath, sections.join('\n\n'), 'context');
 
-  if (output.length > HERMES_AGENTS_MD_HARD_CAP) {
-    throw new Error(
-      `Hermes AGENTS.md (${output.length} chars) exceeds hard cap of ${HERMES_AGENTS_MD_HARD_CAP}. ` +
-      `Hermes truncates above 20K. Trim the priming block or split rule bodies further.`
-    );
-  }
+  assertContextBudget(output, 'AGENTS.md', opts.ruleDelivery?.rules);
 
   if (dryRun) {
     console.log(`[dry-run] Would write AGENTS.md (${output.length} chars, ${Math.round(output.length / 4)} tokens estimated)`);
@@ -398,7 +403,7 @@ when the full AIWG project context is needed.
   if (dryRun) {
     console.log(`[dry-run] Would write .hermes.md (${body.length} chars)`);
   } else {
-    fs.writeFileSync(destPath, body, 'utf8');
+    fs.writeFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
     console.log(`  Created .hermes.md (${body.length} chars)`);
   }
   return 1;
@@ -418,7 +423,7 @@ when the full AIWG project context is needed.
  */
 export function deploySkills(skillDirs, opts) {
   const standardDestDir = paths.skills;
-  const kernelDestDir = kernelSkillsPath;
+  const kernelDestDir = opts.kernelSkillsPath || kernelSkillsPath;
 
   if (!opts.dryRun) {
     console.log(`  Deploying ${skillDirs.length} skills (kernel + standard split)...`);
@@ -432,6 +437,10 @@ export function deploySkills(skillDirs, opts) {
 // ============================================================================
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath, assertContextBudget }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,
@@ -466,7 +475,7 @@ export async function deploy(opts) {
   if ((shouldDeploySkills || skillsOnly) && !opts.commandsOnly && !opts.rulesOnly) {
     const allSkillDirs = [];
 
-    // Addon skills (aiwg-utils, ralph, etc.)
+    // Addon skills, including a direct addon source (#2873, #3035).
     allSkillDirs.push(...getAddonSkillDirs(srcRoot));
 
     // Framework skills
@@ -510,7 +519,7 @@ export async function deploy(opts) {
     const kernelNames = computeAllKernelNames(srcRoot);
     if (kernelNames != null) {
       const desiredKernel = [...kernelNames, 'aiwg-orchestrate'];
-      pruneStaleAiwgSkills(kernelSkillsPath, desiredKernel, opts);
+      pruneStaleAiwgSkills(opts.kernelSkillsPath || kernelSkillsPath, desiredKernel, opts);
 
       // Register kernel skills in Hermes's bundled manifest so the Curator
       // (v0.12.0+, 7-day archival cycle) does not archive them. Standard
@@ -604,7 +613,7 @@ export async function deploy(opts) {
  */
 export function updateBundledManifest(kernelSkillNames, opts) {
   const { dryRun, quiet } = opts;
-  const manifestPath = path.join(kernelSkillsPath, '.bundled_manifest');
+  const manifestPath = path.join(opts.kernelSkillsPath || kernelSkillsPath, '.bundled_manifest');
   const aiwgTag = 'aiwg-managed';
 
   // Read existing manifest (if any) and split into "ours" vs "theirs"
@@ -665,7 +674,11 @@ export function updateBundledManifest(kernelSkillNames, opts) {
  */
 export function migrateLegacySkillPath(opts) {
   const { dryRun, quiet } = opts;
-  const legacyPath = path.join(os.homedir(), '.hermes', '.aiwg', 'skills');
+  // Resolve through the same HERMES_HOME contract as every other path in
+  // this provider (env var first, platform default otherwise): with
+  // HERMES_HOME set, the legacy tree lives under that root — never under
+  // the process home directory.
+  const legacyPath = opts.hermesLegacySkills || path.join(getHermesHome(), '.aiwg', 'skills');
   const newPath = paths.skills;
 
   let legacyExists = false;
@@ -751,7 +764,7 @@ function deployAiwgOrchestrateSkill(srcRoot, opts) {
     return;
   }
 
-  const destDir = path.join(kernelSkillsPath, 'aiwg-orchestrate');
+  const destDir = path.join(opts.kernelSkillsPath || kernelSkillsPath, 'aiwg-orchestrate');
   const destPath = path.join(destDir, 'SKILL.md');
 
   if (fs.existsSync(destPath)) {

package/tools/agents/providers/omp.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import YAML from 'yaml';
-import { resolveOmpPaths } from '../../../src/providers/omp-paths.mjs';
+import { importImpl } from '../../_resolve-impl.mjs';
 import { collectFrameworkArtifacts, getAddonFiles, isKernelSkill, listMdFiles, listSkillDirs, normalizeDeploymentMode, resolveAiwgRoot } from './base.mjs';
 export const name = 'omp';
 export const aliases = ['oh-my-pi'];
@@ -18,7 +18,10 @@ function parse(content) {
 }
 const render = (metadata, body) => `---\n${YAML.stringify(metadata)}---\n\n${body.trim()}\n`;
 function diagnostic(opts, message) { opts.diagnostics?.push(message); if (!opts.quiet) console.warn(`OMP: ${message}`); }
-import { transformAgent, mapModel } from '../../../src/providers/omp-agent.mjs';
+// Resolved through the shared resolver: an installed package ships these
+// modules under dist/src, not src, so a literal path into src fails there.
+const { resolveOmpPaths } = await importImpl(import.meta.url, 'providers/omp-paths.mjs');
+const { transformAgent, mapModel } = await importImpl(import.meta.url, 'providers/omp-agent.mjs');
 export { transformAgent, mapModel };
 const array = value => Array.isArray(value) ? value : typeof value === 'string' ? value.split(',').map(s => s.trim()).filter(Boolean) : [];
 export function transformCommand(src, content, opts = {}) {

package/tools/agents/providers/openclaw-translator.mjs

@@ -120,6 +120,20 @@ function parseBehaviorFrontmatter(content) {
   return frontmatter;
 }
 
+/** Encode a complete YAML double-quoted scalar. */
+function yamlString(value) {
+  return JSON.stringify(value)
+    .replace(/\u0085/g, '\\u0085')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/** Keep metadata within a single line or block comment. */
+function escapeComment(value) {
+  return String(value).replace(/\*\//g, '* /')
+    .replace(/[\r\n\u2028\u2029]/g, (char) => '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0'));
+}
+
 /**
  * Render the HOOK.md content for OpenClaw's hook loader.
  *
@@ -133,15 +147,15 @@ function parseBehaviorFrontmatter(content) {
 export function renderHookMd(behavior) {
   const events = Object.keys(behavior.hooks || {});
   const eventsList = events.length > 0
-    ? events.map((e) => `  - ${e}`).join('\n')
+    ? events.map((e) => `  - ${yamlString(e)}`).join('\n')
     : '  []';
 
-  const description = (behavior.description || '').replace(/"/g, '\\"').slice(0, 200);
+  const description = yamlString((behavior.description || '').slice(0, 200));
 
   return [
     '---',
-    `name: ${behavior.name}`,
-    `description: "${description}"`,
+    `name: ${yamlString(behavior.name)}`,
+    `description: ${description}`,
     'events:',
     eventsList,
     'handler: ./handler.js',
@@ -193,7 +207,7 @@ export function renderHandlerJs(behavior, scriptsRelDir = './scripts') {
 
   return `#!/usr/bin/env node
 // Generated by AIWG (PUW-008/PUW-009). Do not edit; regenerated on \`aiwg use\`.
-// Handler for OpenClaw hook \`${behavior.name}\`. Dispatches to scripts in
+// Handler for OpenClaw hook \`${escapeComment(behavior.name)}\`. Dispatches to scripts in
 // ./scripts/ based on the event delivered by OpenClaw's hook loader.
 //
 // Stdin contract (AIWG canonical, per ADR-3 §3):

package/tools/agents/providers/openclaw.mjs

@@ -26,6 +26,7 @@ try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs;
 import path from 'path';
 import os from 'os';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
   listMdFilesRecursive,
@@ -191,7 +192,7 @@ function deploySkills(skillDirs, opts) {
   // Standard: ~/.openclaw/.aiwg/skills/ (no extra aiwg/ — the .aiwg/ segment IS the namespace)
   const standardDestDir = paths.skills;
   // Kernel: ~/.openclaw/skills/aiwg/ (preserves legacy 2-level namespacing)
-  const kernelDestDir = path.join(kernelSkillsPath, 'aiwg');
+  const kernelDestDir = path.join(opts.kernelSkillsPath || kernelSkillsPath, 'aiwg');
 
   deploySkillsWithKernelRouting(skillDirs, standardDestDir, kernelDestDir, opts);
 
@@ -396,6 +397,10 @@ export function getFileExtension(type) {
 // ============================================================================
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath, resolveOpenClawWorkspace }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     mode,
@@ -485,9 +490,9 @@ export async function deploy(opts) {
     // (`aiwg use` invokes deploy-agents.mjs once per framework + addon
     // batch).
     {
-      const _kernelDestDir = path.isAbsolute(kernelSkillsPath)
+      const _kernelDestDir = opts.kernelSkillsPath || (path.isAbsolute(kernelSkillsPath)
         ? kernelSkillsPath
-        : path.join(target, kernelSkillsPath);
+        : path.join(target, kernelSkillsPath));
       pruneStaleAiwgSkills(_kernelDestDir, computeAllKernelNames(srcRoot), opts);
     }
   }
@@ -549,7 +554,7 @@ export async function deploy(opts) {
       srcRoot, 'agentic', 'code', 'frameworks', 'sdlc-complete', 'templates', 'openclaw', 'AGENTS.md.aiwg-template',
     );
     if (fs.existsSync(templatePath)) {
-      const workspace = resolveOpenClawWorkspace();
+      const workspace = opts.activeWorkspace || resolveOpenClawWorkspace();
       ensureDir(workspace, dryRun);
       if (verbose || !opts.quiet) {
         console.log(`\nBridging AIWG context into ${path.join(workspace, 'AGENTS.md')} + SOUL.md (#1562/#1572)...`);

package/tools/agents/providers/pi.mjs

@@ -11,6 +11,7 @@ import path from 'path';
 import fs from 'fs';
 import {
   collectFrameworkArtifacts,
+  withRuleDeployment,
   createAgentsMdFromTemplate,
   deployFiles,
   deploySkillsWithKernelRouting,
@@ -139,6 +140,10 @@ export function getFileExtension() {
 }
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const normalizedMode = normalizeDeploymentMode(opts.mode);
   const agentFiles = [];
   const commandFiles = [];

package/tools/agents/providers/provider-prepare-channel.mjs

@@ -0,0 +1,5 @@
+// A once-only IPC listener is removed before its async work finishes. Keep the
+// channel referenced until the worker disconnects after publishing its response.
+export function retainPreparationChannel() {
+  process.channel?.ref();
+}