@ghl-ai/aw 0.1.39-beta.8 → 0.1.39

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.39-beta.8",
+  "version": "0.1.39",
   "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",
     "commands/",
     "config.mjs",
+    "codex.mjs",
     "constants.mjs",
     "fmt.mjs",
     "git.mjs",
@@ -23,8 +26,11 @@
     "slack-sim/",
     "file-tree.mjs",
     "apply.mjs",
+    "hook-manifest.mjs",
     "update.mjs",
     "hooks.mjs",
+    "hooks/",
+    "startup.mjs",
     "ecc.mjs",
     "render-rules.mjs",
     "telemetry.mjs"

package/paths.mjs

@@ -3,7 +3,7 @@
 import { existsSync, statSync, lstatSync, readlinkSync } from 'node:fs';
 import { join, resolve, relative, basename, dirname } from 'node:path';
 
-const VALID_TYPES = new Set(['agents', 'skills', 'commands', 'evals']);
+const VALID_TYPES = new Set(['agents', 'skills', 'commands', 'evals', 'references']);
 
 // IDE dirs that may contain symlinks into .aw_registry/
 const IDE_PREFIXES = ['.claude/', '.cursor/', '.codex/', '.agents/'];

package/registry.mjs

@@ -4,7 +4,7 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { createHash } from 'node:crypto';
 
-const TYPE_DIRS = new Set(['agents', 'skills', 'commands', 'evals']);
+const TYPE_DIRS = new Set(['agents', 'skills', 'commands', 'evals', 'references']);
 const SKIP_DIRS = new Set(['docs']);
 
 export function sha256(content) {

package/render-rules.mjs

@@ -1,12 +1,17 @@
-// render-rules.mjs — Render .aw_rules into IDE-specific output files.
+// render-rules.mjs — Render runtime AW rules into IDE-specific output files.
 
 import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { homedir } from 'node:os';
 import * as fmt from './fmt.mjs';
-import { RULES_SOURCE_DIR } from './constants.mjs';
-
-const GENERATED_HEADER = '<!-- Generated by aw — do not edit manually -->\n\n';
+import { RULES_RUNTIME_DIR } from './constants.mjs';
+
+// The marker is placed AFTER the YAML frontmatter so Cursor/Markdown parsers
+// see the frontmatter at byte 0. Putting an HTML comment before --- breaks
+// Cursor's alwaysApply/globs detection.
+const GENERATED_MARKER = '<!-- Generated by aw — do not edit manually -->';
+// Legacy header (pre-pattern comment first) — kept for pruning old files.
+const LEGACY_GENERATED_HEADER = '<!-- Generated by aw — do not edit manually -->\n\n';
 const STACK_OVERLAY_FLAG = 'AW_ENABLE_STACK_OVERLAY_RULES';
 
 /** Rule scope → Cursor .mdc glob patterns */
@@ -160,6 +165,33 @@ function scopeToLabel(scope) {
   return scope.replaceAll('/', ' ');
 }
 
+function toPosixPath(filePath) {
+  return filePath.replaceAll('\\', '/');
+}
+
+function relativeRuleLink(outputDir, targetPath) {
+  return toPosixPath(relative(outputDir, targetPath));
+}
+
+export function resolveRulesSourceDir(cwd, options = {}) {
+  const HOME = options.homeDir || homedir();
+  const candidates = [
+    join(cwd, RULES_RUNTIME_DIR),
+  ];
+
+  if (cwd !== HOME) {
+    candidates.push(
+      join(HOME, RULES_RUNTIME_DIR),
+    );
+  }
+
+  return candidates.find(existsSync) || null;
+}
+
+function rulesRootDir(rulesDir) {
+  return dirname(dirname(rulesDir));
+}
+
 function pruneStaleGeneratedRules(outputDir, expectedFilenames) {
   if (!existsSync(outputDir)) return;
 
@@ -169,7 +201,8 @@ function pruneStaleGeneratedRules(outputDir, expectedFilenames) {
 
     const fullPath = join(outputDir, entry.name);
     const content = readOrNull(fullPath);
-    if (!content?.startsWith(GENERATED_HEADER)) continue;
+    // Match both new pattern (marker after frontmatter) and legacy (marker at top).
+    if (!content || (!content.includes(GENERATED_MARKER) && !content.startsWith(LEGACY_GENERATED_HEADER))) continue;
 
     try {
       unlinkSync(fullPath);
@@ -267,19 +300,101 @@ function renderCursorRules(cwd, rulesDir, options = {}) {
       const refs = readdirSync(referencesDir).filter(f => f.endsWith('.md')).sort();
       if (refs.length > 0) {
         refSection = '\n## References\n\n' +
-          refs.map(f => `- [${f.replace('.md', '')}](.aw_registry/.aw_rules/platform/${scope}/references/${f})`).join('\n') +
+          refs.map((f) => {
+            const targetPath = join(rulesDir, 'platform', scope, 'references', f);
+            const refPath = relativeRuleLink(cursorRulesDir, targetPath);
+            return `- [${f.replace('.md', '')}](${refPath})`;
+          }).join('\n') +
           '\n';
       }
     }
 
-    const content = GENERATED_HEADER + frontmatter.join('\n') + '\n\n' + agentsMd.trim() + '\n' + refSection;
+    // Frontmatter MUST be at byte 0 for Cursor's YAML parser.
+    // Generated marker goes on the line immediately after the closing ---.
+    const content = frontmatter.join('\n') + '\n' + GENERATED_MARKER + '\n\n' + agentsMd.trim() + '\n' + refSection;
     writeFileSync(join(cursorRulesDir, `${scopeToFilename(scope)}.mdc`), content);
     count++;
   }
 
+  // Generate the AW routing rule — this is the hard gate that forces
+  // route selection → stage skill read → follow behavior → respond.
+  const routingRule = generateCursorAwRoutingRule();
+  writeFileSync(join(cursorRulesDir, 'common-aw-routing.mdc'), routingRule);
+  count++;
+
   return count;
 }
 
+function generateCursorAwRoutingRule() {
+  // Frontmatter MUST be at byte 0 for Cursor's alwaysApply/globs detection.
+  return `---
+description: "AW global routing: select route, READ stage skill, then respond"
+alwaysApply: true
+---
+${GENERATED_MARKER}
+
+# AW Global Routing
+
+## Hard Gate (MUST — do not skip)
+
+For every non-trivial request, execute these steps in order before any substantive response:
+
+1. **Load the router** — Read the using-aw-skills SKILL.md from the skills directory.
+
+2. **Select route** — using the decision tree below, pick the smallest correct AW route.
+
+3. **Read the stage skill** — you MUST Read the matching skill file before responding:
+   - /aw-plan → Read aw-plan/SKILL.md
+   - /aw-build → Read aw-build/SKILL.md
+   - /aw-investigate → Read aw-investigate/SKILL.md
+   - /aw-test → Read aw-test/SKILL.md
+   - /aw-review → Read aw-review/SKILL.md
+   - /aw-deploy → Read aw-deploy/SKILL.md
+   - /aw-ship → Read aw-ship/SKILL.md
+
+4. **Follow the skill's behavior** — produce the artifacts the skill defines, not general-knowledge answers.
+
+5. **Then respond** — only after steps 1-4.
+
+Stating a route without Reading the skill file is NOT compliance.
+
+## Route Decision Tree
+
+\`\`\`text
+Does an approved plan/spec already exist for this exact work?
+├── NO → Is the request about a bug, alert, or unclear failure?
+│         ├── YES → /aw-investigate
+│         └── NO  → /aw-plan  ← DEFAULT for anything new
+└── YES → Is the work implemented and needs testing/review?
+          ├── YES → /aw-test or /aw-review
+          └── NO  → Is this a deploy or release action?
+                    ├── YES → /aw-deploy or /aw-ship
+                    └── NO  → /aw-build
+\`\`\`
+
+**Plan-first rule**: New endpoints, services, schemas, features, architecture changes, and integrations ALL go through /aw-plan first. /aw-build requires an approved plan or a mechanical change.
+
+## Default Assumptions
+
+- /aw-plan → write file artifacts under .aw_docs/features/<slug>/ unless user says "chat only".
+- /aw-build → code changes with tests.
+- /aw-investigate → reproduction + root cause evidence.
+
+## Org Rules
+
+After the stage skill is loaded, also read the relevant org rules:
+
+- Always read: universal/AGENTS.md and security/AGENTS.md
+- Then pick the smallest correct domain rule (api-design, backend, data, frontend, infra, mobile, sdet).
+- If repo-local instructions conflict with org-level AW rules, follow org-level.
+
+## Compatibility
+
+- /aw-execute → resolve to /aw-build
+- /aw-verify → resolve to /aw-test or /aw-review
+`;
+}
+
 /** Rule scope → Claude Code paths: frontmatter (only supported field for .claude/rules/) */
 const SCOPE_PATHS = {
   'api-design': ['src/**/*.controller.ts', 'src/**/dto/**/*.ts', 'src/**/*.client.ts'],
@@ -347,12 +462,17 @@ function renderClaudeRules(cwd, rulesDir, options = {}) {
       const refs = readdirSync(referencesDir).filter(f => f.endsWith('.md')).sort();
       if (refs.length > 0) {
         refSection = '\n## References\n\n' +
-          refs.map(f => `- [${f.replace('.md', '')}](.aw_registry/.aw_rules/platform/${scope}/references/${f})`).join('\n') +
+          refs.map((f) => {
+            const targetPath = join(rulesDir, 'platform', scope, 'references', f);
+            const refPath = relativeRuleLink(claudeRulesDir, targetPath);
+            return `- [${f.replace('.md', '')}](${refPath})`;
+          }).join('\n') +
           '\n';
       }
     }
 
-    const content = GENERATED_HEADER + frontmatter + agentsMd.trim() + '\n' + refSection;
+    // Claude Code reads .md frontmatter similarly — keep marker after frontmatter.
+    const content = frontmatter + GENERATED_MARKER + '\n\n' + agentsMd.trim() + '\n' + refSection;
     writeFileSync(join(claudeRulesDir, `${scopeToFilename(scope)}.md`), content);
     count++;
   }
@@ -361,44 +481,144 @@ function renderClaudeRules(cwd, rulesDir, options = {}) {
 }
 
 /**
- * Generate a rules section for CLAUDE.md from .aw_rules.
+ * Generate a rules section for CLAUDE.md from runtime AW rules.
  */
-export function generateClaudeMdRulesSection(rulesDir) {
+/**
+ * Resolve the final scope set for AGENTS.md/CLAUDE.md filtering.
+ * Precedence: explicit option > .aw/config.json awRuleScopes > auto-detect.
+ * Returns undefined if user explicitly disabled filtering (awRuleScopes: "all").
+ */
+export function resolveApplicableScopes(cwd, options = {}) {
+  if (options.applicableScopes) return options.applicableScopes;
+
+  // Read .aw/config.json if present.
+  const configPath = join(cwd, '.aw', 'config.json');
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'));
+      const setting = config.awRuleScopes;
+      if (setting === 'all') return undefined;        // disable filtering
+      if (Array.isArray(setting)) return new Set(setting);
+    } catch { /* fall through to auto-detect */ }
+  }
+
+  return detectApplicableScopes(cwd);
+}
+
+/**
+ * Detect applicable rule scopes for a consumer repo based on filesystem signals.
+ * Returns a Set of scope names (e.g. 'frontend', 'backend', 'mobile').
+ * 'universal' and 'security' are ALWAYS returned (cross-cutting, apply everywhere).
+ */
+export function detectApplicableScopes(cwd) {
+  const scopes = new Set(['universal', 'security']);
+
+  const has = (rel) => existsSync(join(cwd, rel));
+  const readPkg = () => {
+    try {
+      if (!has('package.json')) return null;
+      return JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    } catch {
+      return null;
+    }
+  };
+
+  const pkg = readPkg();
+  if (pkg) {
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    // Frontend signals
+    if (deps.vue || deps.nuxt || deps['@vue/cli-service'] || deps.react || deps.next || deps.svelte) {
+      scopes.add('frontend');
+    }
+    // Backend signals
+    if (deps['@nestjs/core'] || deps.express || deps.fastify || deps.koa || deps['@platform-core/base-service']) {
+      scopes.add('backend');
+      scopes.add('api-design');
+    }
+    // Data signals
+    if (deps.mongoose || deps.typeorm || deps.prisma || deps.knex || deps['@platform-core/firestore']) {
+      scopes.add('data');
+    }
+    // SDET signals
+    if (deps.playwright || deps['@playwright/test'] || deps['@gohighlevel/sdet-platform-core']) {
+      scopes.add('sdet');
+    }
+  }
+
+  if (has('pubspec.yaml')) scopes.add('mobile');               // Flutter/Dart
+  if (has('pom.xml') || has('build.gradle') || has('build.gradle.kts')) scopes.add('backend');
+  if (has('go.mod')) scopes.add('backend');
+  if (has('Cargo.toml')) scopes.add('backend');
+  if (has('requirements.txt') || has('pyproject.toml')) scopes.add('backend');
+
+  // Infra signals
+  if (has('Dockerfile') || has('Jenkinsfile') || has('helm') || has('terraform')) {
+    scopes.add('infra');
+  }
+
+  // If we only found the defaults (universal + security) with no other signals,
+  // return undefined to preserve current behavior (show all rules). Filtering
+  // only kicks in when we positively detect a framework or stack.
+  if (scopes.size <= 2) return undefined;
+  return scopes;
+}
+
+function filterRulesByScopes(rules, applicableScopes) {
+  if (!applicableScopes || applicableScopes.size === 0) return rules;
+  return rules.filter(r => {
+    const scope = String(r.id || '').split('/')[0];
+    return applicableScopes.has(scope);
+  });
+}
+
+export function generateClaudeMdRulesSection(rulesDir, options = {}) {
   const manifest = readManifest(rulesDir);
   if (!manifest) return '';
 
   const mustRules = manifest.rules.filter(r => r.severity === 'MUST');
-  if (mustRules.length === 0) return '';
+  const applicableScopes = options.applicableScopes;
+  const filteredRules = applicableScopes
+    ? filterRulesByScopes(mustRules, applicableScopes)
+    : mustRules;
+  if (filteredRules.length === 0) return '';
 
   const lines = [
     '## Platform Rules (MUST)',
     '',
-    '> Auto-synced from `.aw_registry/.aw_rules/`. Full details in reference files.',
-    '',
+    '> Rendered from platform `.aw/.aw_rules/`. Full details in reference files.',
   ];
 
-  for (const rule of mustRules) {
+  if (applicableScopes) {
+    lines.push(
+      `> Filtered to scopes detected in this repo: \`${[...applicableScopes].sort().join('`, `')}\`. ` +
+      `To override, set \`awRuleScopes\` in \`.aw/config.json\`.`,
+    );
+  }
+  lines.push('');
+
+  for (const rule of filteredRules) {
     lines.push(`- [ ] **${rule.id}** — ${rule.description}`);
   }
 
   lines.push('');
-  lines.push('See `.aw_registry/.aw_rules/rule-manifest.json` for all rules including SHOULD/MAY.');
+  lines.push('See `.aw/.aw_rules/rule-manifest.json` for all rules including SHOULD/MAY.');
   lines.push('');
 
   return lines.join('\n');
 }
 
 /**
- * Generate a rules section for AGENTS.md from the top-level AGENTS.md in .aw_rules.
+ * Generate a rules section for AGENTS.md from the top-level AGENTS.md in runtime AW rules.
  */
 export function generateAgentsMdRulesSection(rulesDir, options = {}) {
   const topLevelAgents = readOrNull(join(rulesDir, 'AGENTS.md'));
   if (!topLevelAgents) return '';
+  const outputDir = options.outputDir || rulesRootDir(rulesDir);
 
   const lines = [
     '## Platform Rules — Non-Negotiables',
     '',
-    '> Auto-synced from `.aw_registry/.aw_rules/`.',
+    '> Rendered from platform `.aw/.aw_rules/`.',
     '',
     topLevelAgents.trim(),
     '',
@@ -407,14 +627,28 @@ export function generateAgentsMdRulesSection(rulesDir, options = {}) {
   // Reference table — tells all IDEs (especially Codex) where to read domain rules.
   // Codex can't auto-trigger by glob, but it CAN read these files when working in
   // the matching area. Keep AGENTS.md lean; full content stays in the source files.
-  const scopes = listRuleScopes(rulesDir, {
+  const allScopes = listRuleScopes(rulesDir, {
     includeNestedScopes: stackOverlaysEnabled(options),
   });
+  // Filter domain scopes by what's relevant to this consumer repo.
+  // 'universal' and 'security' always apply; other domains require detection.
+  const applicableScopes = options.applicableScopes;
+  const isApplicable = (scope) => !applicableScopes
+    || applicableScopes.has(scope)
+    || applicableScopes.has(scope.split('/')[0]);
+  const scopes = allScopes.filter(({ scope }) => isApplicable(scope));
   const domains = scopes.filter(({ scope }) => !scope.includes('/'));
   const overlays = scopes.filter(({ scope }) => scope.includes('/'));
   if (domains.length > 0) {
     lines.push('### Domain Rules');
     lines.push('');
+    if (applicableScopes) {
+      lines.push(
+        `> Filtered to scopes detected in this repo: \`${[...applicableScopes].sort().join('`, `')}\`. ` +
+        `To override, set \`awRuleScopes\` (array or "all") in \`.aw/config.json\`.`,
+      );
+      lines.push('');
+    }
     lines.push('When working in a specific domain, read the matching rules file:');
     lines.push('');
     lines.push('| Domain | Read when editing | Rules file |');
@@ -422,7 +656,8 @@ export function generateAgentsMdRulesSection(rulesDir, options = {}) {
 
     for (const { scope } of domains) {
       const hint = SCOPE_HINTS[scope] || 'Related files';
-      lines.push(`| ${scope} | ${hint} | \`.aw_registry/.aw_rules/platform/${scope}/AGENTS.md\` |`);
+      const rulesFile = relativeRuleLink(outputDir, join(rulesDir, 'platform', scope, 'AGENTS.md'));
+      lines.push(`| ${scope} | ${hint} | \`${rulesFile}\` |`);
     }
     lines.push('');
   }
@@ -437,7 +672,8 @@ export function generateAgentsMdRulesSection(rulesDir, options = {}) {
 
     for (const { scope } of overlays) {
       const hint = SCOPE_HINTS[scope] || 'Stack-specific files';
-      lines.push(`| ${scope} | ${hint} | \`.aw_registry/.aw_rules/platform/${scope}/AGENTS.md\` |`);
+      const rulesFile = relativeRuleLink(outputDir, join(rulesDir, 'platform', scope, 'AGENTS.md'));
+      lines.push(`| ${scope} | ${hint} | \`${rulesFile}\` |`);
     }
     lines.push('');
   }
@@ -447,18 +683,22 @@ export function generateAgentsMdRulesSection(rulesDir, options = {}) {
 
 /**
  * Main render function. Call after aw pull / aw sync.
- * Reads .aw_registry/.aw_rules/ and renders:
+ * Reads runtime .aw/.aw_rules/ and renders:
  *   1. .cursor/rules/<scope>.mdc — at cwd AND at $HOME (global)
  *   2. Returns sections for CLAUDE.md and AGENTS.md injection
  */
 export function renderRules(cwd, options = {}) {
-  const rulesDir = join(cwd, '.aw_registry', RULES_SOURCE_DIR);
-  if (!existsSync(rulesDir)) return { cursorCount: 0, claudeSection: '', agentsSection: '' };
+  const rulesDir = resolveRulesSourceDir(cwd, options);
+  if (!rulesDir) return { cursorCount: 0, claudeSection: '', agentsSection: '' };
+
+  // Resolve applicable scopes for AGENTS.md / CLAUDE.md MUST-rule list.
+  // Order: explicit option → .aw/config.json awRuleScopes → auto-detect.
+  const applicableScopes = resolveApplicableScopes(cwd, options);
 
   const cursorCount = renderCursorRules(cwd, rulesDir, options);
   const claudeCount = renderClaudeRules(cwd, rulesDir, options);
-  const claudeSection = generateClaudeMdRulesSection(rulesDir);
-  const agentsSection = generateAgentsMdRulesSection(rulesDir, options);
+  const claudeSection = generateClaudeMdRulesSection(rulesDir, { applicableScopes });
+  const agentsSection = generateAgentsMdRulesSection(rulesDir, { ...options, outputDir: cwd, applicableScopes });
 
   // Also render to global dirs so rules apply everywhere
   const HOME = options.homeDir || homedir();