@ghl-ai/aw 0.1.39-beta.15 → 0.1.39-beta.16

package/integrate.mjs

@@ -129,8 +129,15 @@ function applyManagedInstructionSections(content, file, rulesSections = {}, opti
     return next ? `${next}\n` : '';
   }
 
-  const appended = sections.join('\n\n').trim();
-  return next ? `${next}\n\n${appended}\n` : `${appended}\n`;
+  // Marker tells users (and aw init) where the managed section starts.
+  // Everything BEFORE this marker is repo-owned and never touched by aw.
+  // Everything AFTER is managed by aw — re-rendered on every aw init.
+  const managedBoundary = '<!-- aw-managed: content below is regenerated by `aw init` — put your own content above this line -->';
+  const appended = [managedBoundary, ...sections].join('\n\n').trim();
+  // Strip any prior managedBoundary line from `next` so we don't accumulate them
+  // when re-running aw init.
+  const cleaned = next.split('\n').filter(line => line.trim() !== managedBoundary).join('\n').trimEnd();
+  return cleaned ? `${cleaned}\n\n${appended}\n` : `${appended}\n`;
 }
 
 /**
@@ -188,28 +195,77 @@ function findFiles(dir, typeName) {
 }
 
 /**
- * Copy AGENTS.md to project root and refresh rules sections in any existing
- * CLAUDE.md. New CLAUDE.md files are intentionally not generated because their
- * routing rules can hijack plugin command dispatch in some workspaces.
+ * Read consumer config to decide whether to write managed sections into
+ * the repo's AGENTS.md / CLAUDE.md.
+ *
+ * Default behaviour: do NOT touch repo-local AGENTS.md/CLAUDE.md. The same
+ * AW Router Bridge + Platform Rules content is already injected into the
+ * GLOBAL files (~/.claude/CLAUDE.md and ~/.codex/AGENTS.md) by aw init,
+ * and Claude/Codex always read those. Modifying the repo file is invasive
+ * and bloats it with content that's already loaded globally.
+ *
+ * Repos that DO want managed sections in their repo file (e.g. for editors
+ * that don't read the global files, or to share AW context with collaborators
+ * who haven't run aw init) can opt in via .aw/config.json:
+ *
+ *   { "writeRepoInstructionFiles": true }
+ *
+ * Existing repo files with managed sections are STRIPPED on next aw init
+ * (so users see the managed content go away — clean migration). Repos with
+ * the opt-in flag get them updated as before.
+ */
+function shouldWriteRepoInstructionFiles(cwd) {
+  const configPath = join(cwd, '.aw', 'config.json');
+  if (!existsSync(configPath)) return false;
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    return config.writeRepoInstructionFiles === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refresh rules sections in any existing AGENTS.md/CLAUDE.md at the repo
+ * root.
+ *
+ * By default, only STRIPS managed sections (we no longer want them in repo
+ * files — they're in global ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md).
+ *
+ * If `writeRepoInstructionFiles: true` is set in `.aw/config.json`, behaves
+ * as before: re-renders the AW Router Bridge + Platform Rules in the repo
+ * file too.
  */
 export function copyInstructions(cwd, tempDir, namespace) {
   const rulesSections = renderRules(cwd);
+  const writeManaged = shouldWriteRepoInstructionFiles(cwd);
   const createdFiles = [];
+
   for (const file of ['AGENTS.md', 'CLAUDE.md']) {
     const dest = join(cwd, file);
     if (existsSync(dest)) {
       const existing = readFileSync(dest, 'utf8');
-      const updated = applyManagedInstructionSections(existing, file, rulesSections, { includeBridge: false });
+      const updated = writeManaged
+        ? applyManagedInstructionSections(existing, file, rulesSections, { includeBridge: false })
+        : applyManagedInstructionSections(existing, file, {}, { includeBridge: false });
 
       if (updated !== existing) {
         writeFileSync(dest, updated);
-        fmt.logSuccess(`Updated ${file}`);
+        if (writeManaged) {
+          fmt.logSuccess(`Updated ${file}`);
+        } else {
+          fmt.logStep(`Stripped aw-managed sections from ${file} (now in ~/.claude/CLAUDE.md / ~/.codex/AGENTS.md)`);
+        }
       }
       continue;
     }
 
     if (file === 'CLAUDE.md') continue;
 
+    // Only CREATE a repo AGENTS.md if writeRepoInstructionFiles is opted in.
+    // Without the opt-in, repo files are user-owned and aw init never creates them.
+    if (!writeManaged) continue;
+
     if (tempDir) {
       const src = join(tempDir, '.aw_registry', file);
       if (existsSync(src)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.39-beta.15",
+  "version": "0.1.39-beta.16",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {

package/render-rules.mjs

@@ -322,62 +322,9 @@ function renderCursorRules(cwd, rulesDir, options = {}) {
   writeFileSync(join(cursorRulesDir, 'common-aw-routing.mdc'), routingRule);
   count++;
 
-  // Generate the prompt-response-format rule — machine-parseable trace
-  // of what skills/rules/MCPs were used during a response.
-  const traceRule = generateCursorPromptTraceRule();
-  writeFileSync(join(cursorRulesDir, 'common-prompt-trace.mdc'), traceRule);
-  count++;
-
   return count;
 }
 
-function generateCursorPromptTraceRule() {
-  // Frontmatter MUST be at byte 0. Machine-parseable JSON block at end of response.
-  return `---
-description: "Append a machine-parseable AW trace at the end of every response"
-alwaysApply: true
----
-${GENERATED_MARKER}
-
-# AW Prompt Trace
-
-At the end of every substantive response, append a JSON-fenced block named \`aw-trace\` with the skills, rules, and MCPs that were loaded or applied during the response.
-
-## Format
-
-\`\`\`aw-trace
-{
-  "route": "/aw-plan",
-  "skills_used": ["using-aw-skills", "aw-plan", "incremental-implementation"],
-  "rules_applied": ["common-aw-routing", "universal", "security", "backend"],
-  "mcps_used": ["context7", "exa-search"],
-  "artifacts_written": [".aw_docs/features/<slug>/spec.md"]
-}
-\`\`\`
-
-## Field semantics
-
-| Field | Type | Required | Notes |
-|---|---|---|---|
-| \`route\` | string | yes | Selected AW route (e.g. \`/aw-plan\`, \`/aw-build\`) |
-| \`skills_used\` | string[] | yes | Skill names actually Read during the response. \`[]\` if none |
-| \`rules_applied\` | string[] | yes | Rule names from \`~/.cursor/rules/*.mdc\` or \`~/.aw_rules/\` that informed the response |
-| \`mcps_used\` | string[] | yes | MCP server names invoked. \`[]\` if none |
-| \`artifacts_written\` | string[] | optional | Files created or modified |
-
-## Rules
-
-- Always include the trace block — even for trivial responses (use \`[]\` for empty arrays).
-- Skill and rule names must match the on-disk basenames (no \`.mdc\` / \`.md\` extension).
-- The trace goes AFTER the substantive response, never before.
-- Do not include skills/rules that were merely "available" — only those that actually influenced this response.
-
-## Why
-
-This makes routing observable. Tools, audits, and compliance checks can parse the trace JSON to verify that the right AW routing happened (route selected → stage skill loaded → relevant rules applied) without scraping prose.
-`;
-}
-
 function generateCursorAwRoutingRule() {
   // Frontmatter MUST be at byte 0 for Cursor's alwaysApply/globs detection.
   return `---
@@ -536,21 +483,120 @@ function renderClaudeRules(cwd, rulesDir, options = {}) {
 /**
  * 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)',
     '',
     '> 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}`);
   }
 
@@ -581,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 |');
@@ -631,10 +691,14 @@ export function renderRules(cwd, options = {}) {
   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, outputDir: cwd });
+  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();