@ghl-ai/aw 0.1.37-beta.63 → 0.1.37-beta.65

package/commands/doctor.mjs

@@ -16,6 +16,8 @@ const STATUS_LABEL = {
 };
 
 const GENERATED_RULE_HEADER = '<!-- Generated by aw — do not edit manually -->';
+const AW_ROUTER_BRIDGE_START_MARKER = '<!-- aw-managed:start router-bridge -->';
+const AW_ROUTER_BRIDGE_END_MARKER = '<!-- aw-managed:end router-bridge -->';
 const PRIMARY_AW_ROUTES = ['plan', 'build', 'test', 'review', 'deploy', 'ship'];
 const CONDITIONAL_AW_ROUTES = ['investigate'];
 const COMPAT_AW_ROUTES = ['execute', 'verify'];
@@ -344,6 +346,16 @@ function textHasRulesReference(text) {
   return text.includes('Platform Rules') && text.includes('.aw_registry/.aw_rules/platform/');
 }
 
+function textHasManagedRouterBridge(text) {
+  return text.includes(AW_ROUTER_BRIDGE_START_MARKER)
+    && text.includes(AW_ROUTER_BRIDGE_END_MARKER)
+    && text.includes('## AW Router Bridge')
+    && text.includes('### 1. Route First (MANDATORY)')
+    && text.includes('### 5. Verify With Proof')
+    && text.includes('using-aw-skills')
+    && text.includes('incremental-implementation');
+}
+
 function extractRegistryReferencePaths(text) {
   const matches = [];
   const pattern = /(?:\]\(|`)([^)\n`]*\.aw_registry\/[^)\n`]+\.md)(?:\)|`)/g;
@@ -443,22 +455,27 @@ function buildDoctorChecks(homeDir, cwd) {
     );
   }
 
-  const homeAgentsPath = join(homeDir, 'AGENTS.md');
-  checks.push(
-    existsSync(homeAgentsPath) && textHasRulesReference(readText(homeAgentsPath))
-      ? makeCheck('home-agents-md', 'Global AGENTS.md', 'pass', 'Global AGENTS.md includes the AW rules reference table')
-      : makeCheck(
-        'home-agents-md',
-        'Global AGENTS.md',
-        rulesDir ? 'fail' : 'warn',
-        existsSync(homeAgentsPath)
-          ? 'Global AGENTS.md is present but missing the AW rules reference table'
-          : 'Global AGENTS.md is missing',
-        'Run `aw init` or `aw pull` to regenerate the managed AGENTS.md instructions.',
-      ),
-  );
-
   if (cwd !== homeDir) {
+    const projectAgentsPath = join(cwd, 'AGENTS.md');
+    const projectClaudePath = join(cwd, 'CLAUDE.md');
+    const projectAgentsHasBridge = existsSync(projectAgentsPath) && textHasManagedRouterBridge(readText(projectAgentsPath));
+    const projectClaudeExists = existsSync(projectClaudePath);
+    const projectClaudeHasBridge = projectClaudeExists && textHasManagedRouterBridge(readText(projectClaudePath));
+
+    checks.push(
+      !projectAgentsHasBridge && !projectClaudeHasBridge
+        ? makeCheck('project-router-bridge', 'Current repo router bridge', 'pass', 'Current repo does not carry a stale managed AW Router Bridge block')
+        : makeCheck(
+          'project-router-bridge',
+          'Current repo router bridge',
+          'warn',
+          projectAgentsHasBridge
+            ? 'Current repo AGENTS.md still carries a stale managed AW Router Bridge block'
+            : 'Current repo CLAUDE.md still carries a stale managed AW Router Bridge block',
+          'Run `aw init` to move the managed AW Router Bridge into the user-home harness files and remove stale repo-local copies.',
+        ),
+    );
+
     const projectClaudeSessionStartStatus = getProjectClaudeSessionStartStatus(cwd);
     if (!projectClaudeSessionStartStatus.ok) {
       checks.push(makeCheck(
@@ -592,6 +609,21 @@ function buildDoctorChecks(homeDir, cwd) {
   );
 
   const claudeRulesDir = join(homeDir, '.claude', 'rules', 'platform');
+  const claudeHomeInstructionsPath = join(homeDir, '.claude', 'CLAUDE.md');
+  checks.push(
+    existsSync(claudeHomeInstructionsPath) && textHasManagedRouterBridge(readText(claudeHomeInstructionsPath))
+      ? makeCheck('claude-home-instructions', 'Claude home instructions', 'pass', 'Claude home CLAUDE.md includes the managed AW Router Bridge block')
+      : makeCheck(
+        'claude-home-instructions',
+        'Claude home instructions',
+        'fail',
+        existsSync(claudeHomeInstructionsPath)
+          ? 'Claude home CLAUDE.md is present but missing the managed AW Router Bridge block'
+          : 'Claude home CLAUDE.md is missing',
+        'Run `aw init` to regenerate ~/.claude/CLAUDE.md with the managed AW Router Bridge block.',
+      ),
+  );
+
   checks.push(
     rulesDir && directoryContainsGeneratedRuleFiles(claudeRulesDir, '.md')
       ? makeCheck('claude-rules', 'Claude AW rules', 'pass', 'Claude has generated platform rules under ~/.claude/rules/platform/')
@@ -695,16 +727,16 @@ function buildDoctorChecks(homeDir, cwd) {
 
   const codexAgentsPath = join(homeDir, '.codex', 'AGENTS.md');
   checks.push(
-    existsSync(codexAgentsPath) && textHasRulesReference(readText(codexAgentsPath))
-      ? makeCheck('codex-agents-md', 'Codex AGENTS.md', 'pass', 'Codex AGENTS.md includes the AW rules reference table')
+    existsSync(codexAgentsPath) && textHasManagedRouterBridge(readText(codexAgentsPath)) && textHasRulesReference(readText(codexAgentsPath))
+      ? makeCheck('codex-agents-md', 'Codex AGENTS.md', 'pass', 'Codex AGENTS.md includes the managed AW Router Bridge block and AW rules reference table')
       : makeCheck(
         'codex-agents-md',
         'Codex AGENTS.md',
         rulesDir ? 'fail' : 'warn',
         existsSync(codexAgentsPath)
-          ? 'Codex AGENTS.md is present but missing the AW rules reference table'
+          ? 'Codex AGENTS.md is present but missing the managed AW Router Bridge block or AW rules reference table'
           : 'Codex AGENTS.md is missing',
-        'Re-run `aw init` so Codex instructions are regenerated with the AW rules reference table.',
+        'Re-run `aw init` so Codex instructions are regenerated with the managed AW Router Bridge block and AW rules reference table.',
       ),
   );
 
@@ -779,6 +811,20 @@ function buildDoctorChecks(homeDir, cwd) {
   );
 
   const cursorRefPath = join(homeDir, '.cursor', 'references', 'route-selection-patterns.md');
+  const cursorAgentsPath = join(homeDir, '.cursor', 'AGENTS.md');
+  checks.push(
+    existsSync(cursorAgentsPath) && textHasManagedRouterBridge(readText(cursorAgentsPath))
+      ? makeCheck('cursor-home-instructions', 'Cursor home instructions', 'pass', 'Cursor home AGENTS.md includes the managed AW Router Bridge block')
+      : makeCheck(
+        'cursor-home-instructions',
+        'Cursor home instructions',
+        'fail',
+        existsSync(cursorAgentsPath)
+          ? 'Cursor home AGENTS.md is present but missing the managed AW Router Bridge block'
+          : 'Cursor home AGENTS.md is missing',
+        'Run `aw init` to regenerate ~/.cursor/AGENTS.md with the managed AW Router Bridge block.',
+      ),
+  );
   checks.push(
     existsSync(cursorRefPath)
       ? makeCheck('cursor-references', 'Cursor shared references', 'pass', 'Cursor shared references are materialized')

package/commands/init.mjs

@@ -23,7 +23,7 @@ import * as config from '../config.mjs';
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
 import { linkWorkspace } from '../link.mjs';
-import { generateCommands, copyInstructions, initAwDocs, syncCodexHomeAgents } from '../integrate.mjs';
+import { generateCommands, copyInstructions, initAwDocs, syncHomeHarnessInstructions } from '../integrate.mjs';
 import { setupMcp } from '../mcp.mjs';
 import { applyStoredStartupPreferences, ensureAwRuntimeHook } from '../startup.mjs';
 import { autoUpdate, promptUpdate } from '../update.mjs';
@@ -64,8 +64,8 @@ function syncInstructionsAndAwDocs(targetDir, namespace) {
 }
 
 function syncHomeAndProjectInstructions(cwd, namespace) {
-  syncInstructionsAndAwDocs(HOME, namespace);
-  syncCodexHomeAgents(HOME);
+  syncHomeHarnessInstructions(HOME);
+  initAwDocs(HOME);
   if (cwd !== HOME) {
     syncInstructionsAndAwDocs(cwd, namespace);
   }

package/commands/pull.mjs

@@ -30,7 +30,7 @@ import {
 } from '../constants.mjs';
 import { collectAllPaths, syncFileTree } from '../file-tree.mjs';
 import { linkWorkspace } from '../link.mjs';
-import { generateCommands, copyInstructions, syncCodexHomeAgents } from '../integrate.mjs';
+import { generateCommands, copyInstructions, syncHomeHarnessInstructions } from '../integrate.mjs';
 import { removeWorkspaceHookDefaults } from '../codex.mjs';
 import { applyStoredStartupPreferences, ensureAwRuntimeHook } from '../startup.mjs';
 
@@ -255,8 +255,7 @@ export async function pullCommand(args) {
       const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
       ideSpinner.message('Generating commands...');
       const commands = generateCommands(HOME, { silent: true });
-      copyInstructions(HOME, null, cfg.namespace);
-      syncCodexHomeAgents(HOME);
+      syncHomeHarnessInstructions(HOME);
       ensureAwRuntimeHook(HOME);
       applyStoredStartupPreferences(HOME);
       if (startupCleanupDir) removeWorkspaceHookDefaults(startupCleanupDir);
@@ -264,8 +263,7 @@ export async function pullCommand(args) {
     } else {
       linkWorkspace(HOME, awDirForLinks, { silent: true });
       generateCommands(HOME, { silent: true });
-      copyInstructions(HOME, null, cfg.namespace);
-      syncCodexHomeAgents(HOME);
+      syncHomeHarnessInstructions(HOME);
       ensureAwRuntimeHook(HOME);
       applyStoredStartupPreferences(HOME);
       if (startupCleanupDir) removeWorkspaceHookDefaults(startupCleanupDir);

package/integrate.mjs

@@ -1,13 +1,14 @@
 // integrate.mjs — Generate commands for all IDEs, instructions (CLAUDE.md, AGENTS.md)
 
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import * as fmt from './fmt.mjs';
 import * as config from './config.mjs';
 import { getLocalRegistryDir } from './git.mjs';
 import {
   generateAgentsMdRulesSection,
+  generateClaudeMdRulesSection,
   renderRules,
   resolveRulesSourceDir,
 } from './render-rules.mjs';
@@ -22,22 +23,39 @@ function generateAwRouterBridgeSection() {
   return `${AW_ROUTER_BRIDGE_START_MARKER}
 ## ${AW_ROUTER_BRIDGE_HEADER}
 
-Before any substantive response on every new user turn, you MUST first resolve and apply \`$HOME/.codex/skills/using-aw-skills/SKILL.md\`, then use it to select the smallest correct AW route and stage skill for the current request.
-You MUST resolve and read the applicable AW rules from \`$HOME/.aw/.aw_registry/.aw_rules/platform/<domain>/AGENTS.md\`, and you MUST also read \`$HOME/.aw/.aw_registry/.aw_rules/platform/universal/AGENTS.md\` plus \`$HOME/.aw/.aw_registry/.aw_rules/platform/security/AGENTS.md\` whenever those cross-cutting rules apply.
-You MUST NOT assume any previously used skill remains active; re-evaluate and re-select the required AW skill stack on each turn.
-When repo-local instructions conflict with these user-home AW skill or AW rules sources of truth, you MUST follow the user-home sources of truth.
-
-## Engineering Principles
-
-Use \`using-aw-skills\` first to choose the smallest correct AW route before exploration, planning, implementation, testing, or review.
-Before proposing or writing code, first inspect the existing code paths, adjacent patterns, configs, generated artifacts, and tests that already implement similar behavior in this repo.
-For non-trivial work, explore the relevant platform docs, app surfaces, harness behavior, and integration points before choosing an approach; prefer extending existing patterns over inventing new ones.
-If requirements, product intent, or behavioral consequences are ambiguous and cannot be resolved from code, docs, or tests, ask a short clarifying question before making a risky change.
-For bug fixes and behavior changes, prefer a Red -> Green -> Refactor loop, using \`aw-debug\`, \`aw-build\`, \`aw-test\`, and \`aw-review\` as needed.
-For multi-step implementation work, use \`incremental-implementation\` to break the work into thin, reversible slices with clear validation at each step before moving on.
-When the request still needs a tighter execution contract, use \`aw-plan\`.
-When changing interfaces or config contracts, follow \`interface-stability\`.
-Verify the exact changed surface with focused tests, static checks, or runtime probes before claiming success.
+### 1. Route First (MANDATORY)
+- Before any substantive response, resolve and apply \`using-aw-skills\`
+- Select the smallest correct AW route and stage skill for this task
+- Do not assume the previous skill stack is still active
+
+### 2. Read Rules Before Acting (MANDATORY)
+- Read applicable AW rules from \`$HOME/.aw/.aw_registry/.aw_rules/platform/<domain>/AGENTS.md\`
+- Also read \`universal\` and \`security\` rules whenever they apply
+- If repo-local instructions conflict with org-level sources of truth, follow org-level sources
+
+### 3. Explore Before Building
+- Read existing code, adjacent patterns, configs, generated artifacts, and tests before writing anything
+- For non-trivial work, inspect platform docs, runtime behavior, app surfaces, and integration boundaries first
+- Ask one short clarifying question only when ambiguity remains after exploration
+
+### 4. Build in Small Steps
+- For multi-step work, resolve and apply \`incremental-implementation\`
+- Break work into thin, reversible slices with validation at each step
+- Prefer extending existing patterns over inventing new ones
+- Never batch unrelated changes in one pass
+
+### 5. Verify With Proof
+- For bug fixes and behavior changes, use Red -> Green -> Refactor
+- For config, docs, scaffolding, and integration wiring, use focused verification appropriate to the changed surface
+- Use \`aw-debug\`, \`aw-build\`, \`aw-test\`, and \`aw-review\` as needed
+- Never mark work complete without focused proof
+
+### 6. Core Principles
+- Correctness over cleverness
+- Clarity over complexity
+- Small diffs over broad rewrites
+- Evidence over assumption
+- When corrected, update the working pattern and do not repeat the same mistake
 ${AW_ROUTER_BRIDGE_END_MARKER}`;
 }
 
@@ -73,16 +91,17 @@ function stripManagedSection(content, header, stopHeaders = []) {
   return `${content.slice(0, idx).trimEnd()}${content.slice(end)}`;
 }
 
-function applyManagedInstructionSections(content, file, rulesSections = {}) {
+function applyManagedInstructionSections(content, file, rulesSections = {}, options = {}) {
   const rulesHeader = file === 'CLAUDE.md' ? CLAUDE_RULES_HEADER : AGENTS_RULES_HEADER;
   const rulesSection = file === 'CLAUDE.md' ? rulesSections.claudeSection : rulesSections.agentsSection;
+  const includeBridge = options.includeBridge !== false;
 
   let next = stripManagedBlock(content, AW_ROUTER_BRIDGE_START_MARKER, AW_ROUTER_BRIDGE_END_MARKER);
   next = stripManagedSection(next, AW_ROUTER_BRIDGE_HEADER, [rulesHeader]);
   next = stripManagedSection(next, rulesHeader);
   next = next.trimEnd();
 
-  const sections = [generateAwRouterBridgeSection(), rulesSection].filter(Boolean);
+  const sections = [includeBridge ? generateAwRouterBridgeSection() : null, rulesSection].filter(Boolean);
   if (sections.length === 0) {
     return next ? `${next}\n` : '';
   }
@@ -157,7 +176,7 @@ export function copyInstructions(cwd, tempDir, namespace) {
     const dest = join(cwd, file);
     if (existsSync(dest)) {
       const existing = readFileSync(dest, 'utf8');
-      const updated = applyManagedInstructionSections(existing, file, rulesSections);
+      const updated = applyManagedInstructionSections(existing, file, rulesSections, { includeBridge: false });
 
       if (updated !== existing) {
         writeFileSync(dest, updated);
@@ -175,7 +194,7 @@ export function copyInstructions(cwd, tempDir, namespace) {
         if (namespace) {
           content = content.replace(/\{\{TEAM\}\}/g, namespace);
         }
-        content = applyManagedInstructionSections(content, file, rulesSections);
+        content = applyManagedInstructionSections(content, file, rulesSections, { includeBridge: false });
         writeFileSync(dest, content);
         fmt.logSuccess(`Created ${file}`);
         createdFiles.push(dest);
@@ -185,7 +204,7 @@ export function copyInstructions(cwd, tempDir, namespace) {
 
     const content = generateAgentsMd(cwd, namespace, rulesSections);
     if (content) {
-      writeFileSync(dest, content);
+      writeFileSync(dest, applyManagedInstructionSections(content, file, rulesSections, { includeBridge: false }));
       fmt.logSuccess(`Created ${file}`);
       createdFiles.push(dest);
     }
@@ -193,25 +212,48 @@ export function copyInstructions(cwd, tempDir, namespace) {
   return createdFiles;
 }
 
-export function syncCodexHomeAgents(homeDir = homedir()) {
-  const codexAgentsPath = join(homeDir, '.codex', 'AGENTS.md');
-  const rulesDir = resolveRulesSourceDir(homeDir, { homeDir });
-  if (!rulesDir) return null;
+function syncHomeInstructionFile(destPath, file, rulesSection) {
+  const existing = existsSync(destPath)
+    ? readFileSync(destPath, 'utf8')
+    : (file === 'CLAUDE.md' ? '# CLAUDE.md\n' : '# AGENTS.md\n');
+  const updated = applyManagedInstructionSections(
+    existing,
+    file,
+    file === 'CLAUDE.md' ? { claudeSection: rulesSection } : { agentsSection: rulesSection },
+  );
 
-  const rulesSection = generateAgentsMdRulesSection(rulesDir, {
-    outputDir: join(homeDir, '.codex'),
-  });
-  if (!rulesSection) return null;
-  const normalizedRulesSection = rulesSection.replaceAll('../.aw/.aw_registry/', '../.aw_registry/');
-
-  const existing = existsSync(codexAgentsPath) ? readFileSync(codexAgentsPath, 'utf8') : '# AGENTS\n';
-  const withoutRules = stripManagedSection(existing, AGENTS_RULES_HEADER).trimEnd();
-  const updated = withoutRules ? `${withoutRules}\n\n${normalizedRulesSection}\n` : `${normalizedRulesSection}\n`;
   if (updated === existing) return null;
 
-  mkdirSync(join(homeDir, '.codex'), { recursive: true });
-  writeFileSync(codexAgentsPath, updated);
-  return codexAgentsPath;
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, updated);
+  return destPath;
+}
+
+export function syncHomeHarnessInstructions(homeDir = homedir()) {
+  const rulesDir = resolveRulesSourceDir(homeDir, { homeDir });
+  const codexRulesSection = rulesDir
+    ? generateAgentsMdRulesSection(rulesDir, {
+      outputDir: join(homeDir, '.codex'),
+    }).replaceAll('../.aw/.aw_registry/', '../.aw_registry/')
+    : '';
+  const cursorRulesSection = rulesDir
+    ? generateAgentsMdRulesSection(rulesDir, {
+      outputDir: join(homeDir, '.cursor'),
+    }).replaceAll('../.aw/.aw_registry/', '../.aw_registry/')
+    : '';
+  const claudeRulesSection = rulesDir ? generateClaudeMdRulesSection(rulesDir) : '';
+
+  return [
+    syncHomeInstructionFile(join(homeDir, '.codex', 'AGENTS.md'), 'AGENTS.md', codexRulesSection),
+    syncHomeInstructionFile(join(homeDir, '.claude', 'CLAUDE.md'), 'CLAUDE.md', claudeRulesSection),
+    syncHomeInstructionFile(join(homeDir, '.cursor', 'AGENTS.md'), 'AGENTS.md', cursorRulesSection),
+  ].filter(Boolean);
+}
+
+export function syncCodexHomeAgents(homeDir = homedir()) {
+  const codexAgentsPath = join(homeDir, '.codex', 'AGENTS.md');
+  syncHomeHarnessInstructions(homeDir);
+  return existsSync(codexAgentsPath) ? codexAgentsPath : null;
 }
 
 function generateClaudeMd(cwd, namespace, rulesSections = {}) {

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.37-beta.63",
+  "version": "0.1.37-beta.65",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
-  "bin": "bin.js",
+  "bin": {
+    "aw": "bin.js"
+  },
   "files": [
     "bin.js",
     "cli.mjs",