contextos-agents 1.6.1 → 1.7.0

package/.agents/core/skills/vercel-optimize/scripts/merge-signals.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * merge-signals.mjs
+ * Merges Vercel telemetry production metrics with codebase route scan outputs.
+ *
+ * Usage:
+ *   node scripts/merge-signals.mjs <signals-file> <codebase-file> [--out <file>] [--help]
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function printHelp() {
+  console.log(`
+merge-signals.mjs — Correlates Telemetry Metrics with Codebase Routes
+
+Usage:
+  node scripts/merge-signals.mjs <signals-file> <codebase-file> [options]
+
+Arguments:
+  signals-file           JSON file generated by collect-signals.mjs
+  codebase-file          JSON file generated by scan-codebase.mjs
+
+Options:
+  --out <file>           Output destination file (default: stdout)
+  --help, -h             Show this help message
+`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args.length < 2) {
+  printHelp();
+  process.exit(args.includes('--help') || args.includes('-h') ? 0 : 1);
+}
+
+const positional = [];
+let outFile = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--out' && i + 1 < args.length) {
+    outFile = args[++i];
+  } else if (!arg.startsWith('-')) {
+    positional.push(arg);
+  }
+}
+
+if (positional.length < 2) {
+  console.error('Error: Both <signals-file> and <codebase-file> are required.');
+  process.exit(1);
+}
+
+const [signalsPath, codebasePath] = positional;
+if (!existsSync(signalsPath)) {
+  console.error(`Error: File not found: ${signalsPath}`);
+  process.exit(1);
+}
+if (!existsSync(codebasePath)) {
+  console.error(`Error: File not found: ${codebasePath}`);
+  process.exit(1);
+}
+
+let signalsData = {};
+let codebaseData = {};
+
+try {
+  signalsData = JSON.parse(readFileSync(resolve(process.cwd(), signalsPath), 'utf8'));
+} catch (e) {
+  console.error(`Error parsing signals JSON: ${e.message}`);
+  process.exit(1);
+}
+
+try {
+  codebaseData = JSON.parse(readFileSync(resolve(process.cwd(), codebasePath), 'utf8'));
+} catch (e) {
+  console.error(`Error parsing codebase JSON: ${e.message}`);
+  process.exit(1);
+}
+
+const telemetryRoutes = signalsData.routes || [];
+const codeRoutes = codebaseData.routes || [];
+
+// Correlate metrics with source files
+const mergedRoutes = [];
+
+for (const tr of telemetryRoutes) {
+  // Find matching route in codebase
+  const match = codeRoutes.find(cr => {
+    return cr.route === tr.route || cr.route === tr.route + '/' || tr.route === cr.route + '/';
+  });
+
+  mergedRoutes.push({
+    ...tr,
+    file: match ? match.file : null,
+    frameworkConfig: match ? {
+      type: match.type,
+      dynamic: match.dynamic,
+      revalidate: match.revalidate,
+      runtime: match.runtime
+    } : null
+  });
+}
+
+// Add codebase routes that had no telemetry records
+for (const cr of codeRoutes) {
+  const existing = mergedRoutes.some(mr => mr.file === cr.file || mr.route === cr.route);
+  if (!existing) {
+    mergedRoutes.push({
+      route: cr.route,
+      method: 'GET',
+      invocations: 0,
+      p95DurationMs: 0,
+      avgDurationMs: 0,
+      coldStartRate: 0,
+      errorRate: 0,
+      cacheable: cr.dynamic === 'force-static' || cr.revalidate != null,
+      file: cr.file,
+      frameworkConfig: {
+        type: cr.type,
+        dynamic: cr.dynamic,
+        revalidate: cr.revalidate,
+        runtime: cr.runtime
+      }
+    });
+  }
+}
+
+const merged = {
+  timestamp: new Date().toISOString(),
+  projectId: signalsData.projectId || 'unknown',
+  windowDays: signalsData.windowDays || 14,
+  framework: codebaseData.framework || 'unknown',
+  metrics: signalsData.metrics || {},
+  middleware: codebaseData.middleware || [],
+  routes: mergedRoutes
+};
+
+const outputJson = JSON.stringify(merged, null, 2);
+if (outFile) {
+  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
+} else {
+  console.log(outputJson);
+}

package/.agents/core/skills/vercel-optimize/scripts/scan-codebase.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * scan-codebase.mjs
+ * Scans repository routes, middleware, and rendering directives for Vercel optimization.
+ *
+ * Usage:
+ *   node scripts/scan-codebase.mjs <repo-root> [--out <file>] [--help]
+ */
+
+import { readdirSync, statSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, join, relative, basename } from 'node:path';
+
+function printHelp() {
+  console.log(`
+scan-codebase.mjs — Vercel Codebase Route & Config Scanner
+
+Usage:
+  node scripts/scan-codebase.mjs <repo-root> [options]
+
+Arguments:
+  repo-root              Path to the repository root directory to scan
+
+Options:
+  --out <file>           Output file path (default: stdout)
+  --help, -h             Show this help message
+`);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  printHelp();
+  process.exit(0);
+}
+
+let repoRoot = null;
+let outFile = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--out' && i + 1 < args.length) {
+    outFile = args[++i];
+  } else if (!arg.startsWith('-') && !repoRoot) {
+    repoRoot = resolve(process.cwd(), arg);
+  }
+}
+
+if (!repoRoot || !existsSync(repoRoot)) {
+  console.error(`Error: Repository path not found: ${repoRoot}`);
+  process.exit(1);
+}
+
+// Detect framework
+let framework = 'unknown';
+const pkgPath = join(repoRoot, 'package.json');
+if (existsSync(pkgPath)) {
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (deps.next) framework = 'nextjs';
+    else if (deps['@sveltejs/kit']) framework = 'sveltekit';
+    else if (deps.nuxt) framework = 'nuxt';
+    else if (deps.astro) framework = 'astro';
+    else if (deps.react) framework = 'react';
+  } catch {
+    // Ignore error
+  }
+}
+
+const routes = [];
+const middleware = [];
+
+function walk(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.next' || entry.name === 'dist') {
+      continue;
+    }
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(fullPath);
+    } else if (entry.isFile()) {
+      const relPath = relative(repoRoot, fullPath).replace(/\\/g, '/');
+      const filename = basename(entry.name);
+
+      // Check middleware
+      if (/^middleware\.(ts|js|mjs)$/.test(filename) || /^src\/middleware\.(ts|js|mjs)$/.test(relPath)) {
+        try {
+          const content = readFileSync(fullPath, 'utf8');
+          middleware.push({
+            file: relPath,
+            hasMatcher: content.includes('matcher:'),
+            runtime: content.includes("runtime = 'edge'") ? 'edge' : 'nodejs'
+          });
+        } catch {}
+      }
+
+      // Check App Router route handlers
+      if (/^(route|page)\.(ts|tsx|js|jsx)$/.test(filename) && (relPath.includes('app/') || relPath.includes('src/app/'))) {
+        try {
+          const content = readFileSync(fullPath, 'utf8');
+          const isRoute = filename.startsWith('route');
+          const isDynamic = content.includes("dynamic = 'force-dynamic'") || content.includes('export const dynamic = "force-dynamic"');
+          const isStatic = content.includes("dynamic = 'force-static'") || content.includes('export const dynamic = "force-static"');
+          const hasRevalidate = /revalidate\s*=\s*(\d+)/.test(content);
+          const revalidateVal = hasRevalidate ? parseInt(content.match(/revalidate\s*=\s*(\d+)/)[1], 10) : null;
+          const runtime = content.includes("runtime = 'edge'") ? 'edge' : 'nodejs';
+
+          // Extract route pattern
+          let routeUrl = relPath
+            .replace(/^(src\/)?app/, '')
+            .replace(/\/(route|page)\.(ts|tsx|js|jsx)$/, '');
+          if (!routeUrl.startsWith('/')) routeUrl = '/' + routeUrl;
+          if (routeUrl === '') routeUrl = '/';
+
+          routes.push({
+            type: isRoute ? 'api-route' : 'page-route',
+            route: routeUrl,
+            file: relPath,
+            dynamic: isDynamic ? 'force-dynamic' : (isStatic ? 'force-static' : 'auto'),
+            revalidate: revalidateVal,
+            runtime
+          });
+        } catch {}
+      }
+
+      // Check Pages Router API handlers
+      if ((relPath.includes('pages/api/') || relPath.includes('src/pages/api/')) && /\.(ts|js)$/.test(filename)) {
+        try {
+          const content = readFileSync(fullPath, 'utf8');
+          let routeUrl = relPath
+            .replace(/^(src\/)?pages/, '')
+            .replace(/\.(ts|js)$/, '');
+          if (routeUrl.endsWith('/index')) routeUrl = routeUrl.slice(0, -6);
+
+          routes.push({
+            type: 'api-route',
+            route: routeUrl,
+            file: relPath,
+            dynamic: 'pages-api',
+            runtime: content.includes("runtime = 'edge'") ? 'edge' : 'nodejs'
+          });
+        } catch {}
+      }
+    }
+  }
+}
+
+walk(repoRoot);
+
+const result = {
+  timestamp: new Date().toISOString(),
+  repoRoot: relative(process.cwd(), repoRoot).replace(/\\/g, '/') || '.',
+  framework,
+  summary: {
+    totalRoutes: routes.length,
+    apiRoutes: routes.filter(r => r.type === 'api-route').length,
+    pageRoutes: routes.filter(r => r.type === 'page-route').length,
+    middlewareCount: middleware.length
+  },
+  middleware,
+  routes
+};
+
+const outputJson = JSON.stringify(result, null, 2);
+if (outFile) {
+  writeFileSync(resolve(process.cwd(), outFile), outputJson, 'utf8');
+} else {
+  console.log(outputJson);
+}

package/.agents/core/skills/vercel-optimize/skill.yaml

@@ -1,4 +1,5 @@
 name: vercel-optimize
+type: runtime
 description: Observability-first Vercel performance and cost reduction optimization skill.
 tags:
   - vercel
@@ -8,3 +9,10 @@ tags:
 version: 1.2.0
 requires:
   - nextjs
+resources:
+  - SKILL.md
+  - VALIDATION.json
+  - scripts/collect-signals.mjs
+  - scripts/gate-investigations.mjs
+  - scripts/merge-signals.mjs
+  - scripts/scan-codebase.mjs

package/.agents/core/skills/web-accessibility/skill.yaml

@@ -1,6 +1,7 @@
 id: web-accessibility
 name: Web Accessibility
 category: frontend
+type: instruction-only
 tags: [frontend, a11y, wcag, aria, accessibility]
 requires: []
 optional: [react, nextjs]
@@ -8,3 +9,9 @@ conflicts: []
 weight: 7
 documents:
   - accessibility.md
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json
+  - accessibility.md

package/.agents/ctx.js

@@ -370,7 +370,20 @@ if (command === 'export') {
 // ── doctor ────────────────────────────────────────────────────────────────────
 } else if (command === 'doctor') {
   const doctorModule = require('./doctor.js');
-  doctorModule.runDoctor(process.cwd());
+  const res = doctorModule.runDoctor(process.cwd(), { json: args.includes('--json') });
+  if (res && res.ok === false) {
+    process.exit(1);
+  }
+
+// ── status ────────────────────────────────────────────────────────────────────
+} else if (command === 'status') {
+  const commands = require(path.join(__dirname, '..', 'bin', 'commands.js'));
+  const status = commands.getStatus(process.cwd());
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(status, null, 2));
+  } else {
+    console.log(commands.formatStatusText(status));
+  }
 
 // ── stats ─────────────────────────────────────────────────────────────────────
 } else if (command === 'stats') {

package/.agents/doctor.js

@@ -112,6 +112,100 @@ function checkCompiledAdapters(projectDir) {
   return compiled;
 }
 
+function checkLockfileIntegrity(projectDir) {
+  const lockPath = path.join(projectDir, '.agents', 'contextos.lock.json');
+  if (!fs.existsSync(lockPath)) {
+    return { ok: true, exists: false, isError: false, message: 'none (not generated yet)' };
+  }
+  try {
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object') {
+      return { ok: false, exists: true, isError: true, error: 'Lockfile JSON root is not an object' };
+    }
+    if (!data.schemaVersion || typeof data.schemaVersion !== 'number') {
+      return { ok: false, exists: true, isError: true, error: 'Lockfile missing valid schemaVersion' };
+    }
+    if (!data.managedFiles || typeof data.managedFiles !== 'object') {
+      return { ok: false, exists: true, isError: true, error: 'Lockfile missing managedFiles map' };
+    }
+    const count = Object.keys(data.managedFiles).length;
+    return { ok: true, exists: true, isError: false, message: `valid (v${data.schemaVersion}, ${count} managed files)` };
+  } catch (err) {
+    return { ok: false, exists: true, isError: true, error: `Lockfile is corrupted JSON: ${err.message}` };
+  }
+}
+
+function checkAdapterIntegrity(projectDir) {
+  const errors = [];
+  const filesToCheck = [
+    path.join(projectDir, '.cursorrules'),
+    path.join(projectDir, '.github', 'copilot-instructions.md'),
+    path.join(projectDir, '.aider.conf.yml'),
+    path.join(projectDir, '.zed', 'rules.md'),
+  ];
+  for (const f of filesToCheck) {
+    if (fs.existsSync(f)) {
+      try {
+        const stat = fs.statSync(f);
+        if (stat.size === 0) {
+          errors.push(`Adapter file ${path.relative(projectDir, f).replace(/\\/g, '/')} is empty (0 bytes)`);
+        }
+      } catch {
+        errors.push(`Adapter file ${path.relative(projectDir, f).replace(/\\/g, '/')} is unreadable`);
+      }
+    }
+  }
+
+  const cursorRulesDir = path.join(projectDir, '.cursor', 'rules');
+  if (fs.existsSync(cursorRulesDir)) {
+    try {
+      const files = fs.readdirSync(cursorRulesDir);
+      for (const file of files) {
+        const full = path.join(cursorRulesDir, file);
+        if (fs.statSync(full).size === 0) {
+          errors.push(`Cursor rule ${file} is empty (0 bytes)`);
+        }
+      }
+    } catch {}
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function checkSymlinks(projectDir) {
+  const errors = [];
+  const targetDir = path.join(projectDir, '.agents');
+  if (!fs.existsSync(targetDir)) return { ok: true, errors: [] };
+
+  function scan(current) {
+    let entries;
+    try {
+      entries = fs.readdirSync(current);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      const full = path.join(current, name);
+      try {
+        const lstat = fs.lstatSync(full);
+        if (lstat.isSymbolicLink()) {
+          if (!fs.existsSync(full)) {
+            errors.push(`Broken symlink: ${path.relative(projectDir, full).replace(/\\/g, '/')}`);
+          }
+        } else if (lstat.isDirectory()) {
+          scan(full);
+        }
+      } catch {
+        errors.push(`Cannot stat file: ${path.relative(projectDir, full).replace(/\\/g, '/')}`);
+      }
+    }
+  }
+
+  scan(targetDir);
+  return { ok: errors.length === 0, errors };
+}
+
 function inspectSkills(projectDir, activeProfile) {
   const skillsDir = path.join(projectDir, '.agents', 'core', 'skills');
   if (!fs.existsSync(skillsDir)) return { total: 0, active: 0, excluded: 0, byDomain: { frontend: [], backend: [], cross: [] } };
@@ -139,18 +233,47 @@ function inspectSkills(projectDir, activeProfile) {
   };
 }
 
-function runDoctor(projectDir = process.cwd()) {
+function runDoctor(projectDir = process.cwd(), options = {}) {
   const version = (() => {
     try {
       return require('../package.json').version;
     } catch {
-      return '1.5.0';
+      return '1.7.0';
     }
   })();
 
+  const isJson = Boolean(options.json);
+  const errors = [];
+  const warnings = [];
+
   const agentsDir = path.join(projectDir, '.agents');
   const hasAgents = fs.existsSync(agentsDir);
+  if (!hasAgents) {
+    errors.push('.agents/ directory missing (run: npx contextos-agents init)');
+  }
+
   const nodeCheck = checkNodeVersion();
+  if (!nodeCheck.ok) {
+    errors.push(nodeCheck.message);
+  }
+
+  const lockfileCheck = checkLockfileIntegrity(projectDir);
+  if (!lockfileCheck.ok) {
+    errors.push(lockfileCheck.error);
+  } else if (!lockfileCheck.exists && hasAgents) {
+    warnings.push('Lockfile missing (.agents/contextos.lock.json)');
+  }
+
+  const adapterCheck = checkAdapterIntegrity(projectDir);
+  if (!adapterCheck.ok) {
+    errors.push(...adapterCheck.errors);
+  }
+
+  const symlinkCheck = checkSymlinks(projectDir);
+  if (!symlinkCheck.ok) {
+    errors.push(...symlinkCheck.errors);
+  }
+
   const activeProfile = hasAgents ? profiles.getActiveProfile(projectDir) : null;
   const skillsInfo = inspectSkills(projectDir, activeProfile);
   const compiledAdapters = checkCompiledAdapters(projectDir);
@@ -162,6 +285,34 @@ function runDoctor(projectDir = process.cwd()) {
   const secretCheck = checkSecretScanner(projectDir);
   const stack = profiles.detectStack(projectDir);
 
+  const ok = errors.length === 0;
+
+  if (isJson) {
+    const report = {
+      ok,
+      version,
+      errors,
+      warnings,
+      hasAgents,
+      nodeOk: nodeCheck.ok,
+      activeProfile,
+      skillsInfo,
+      compiledAdapters,
+      hasMcp,
+      hookCheck,
+      secretCheck,
+      lockfileCheck,
+      adapterCheck,
+      symlinkCheck,
+      stack,
+    };
+    console.log(JSON.stringify(report, null, 2));
+    if (options.exitOnError !== false && !ok && require.main === module) {
+      process.exit(1);
+    }
+    return report;
+  }
+
   console.log('\n┌─────────────────────────────────────────────────────────────┐');
   console.log(`│  ContextOS Doctor — Project Health Check  v${version.padEnd(16)}│`);
   console.log('├─────────────────────────────────────────────────────────────┤');
@@ -178,6 +329,15 @@ function runDoctor(projectDir = process.cwd()) {
   const nodeIcon = nodeCheck.ok ? '✓' : '✗';
   console.log(`│  ${nodeIcon} ${nodeCheck.message.padEnd(58)}│`);
 
+  // Lockfile
+  if (lockfileCheck.exists) {
+    const lockIcon = lockfileCheck.ok ? '✓' : '✗';
+    const lockStr = `Lockfile: ${lockfileCheck.ok ? lockfileCheck.message : lockfileCheck.error}`;
+    console.log(`│  ${lockIcon} ${lockStr.slice(0, 58).padEnd(58)}│`);
+  } else {
+    console.log('│  • Lockfile: not present (optional for dev repository)      │');
+  }
+
   // Active profile
   if (activeProfile) {
     const profStr = `Active profile: ${activeProfile.name || activeProfile.profile}`;
@@ -199,6 +359,11 @@ function runDoctor(projectDir = process.cwd()) {
     console.log('│  • Adapters compiled: none (run: contextos export gemini)   │');
   }
 
+  // Symlinks
+  const symIcon = symlinkCheck.ok ? '✓' : '✗';
+  const symStr = symlinkCheck.ok ? 'Symlinks: verified (0 broken)' : `Broken symlinks: ${symlinkCheck.errors.length}`;
+  console.log(`│  ${symIcon} ${symStr.padEnd(58)}│`);
+
   // MCP
   if (hasMcp) {
     console.log('│  ✓ MCP server: installed (.agents/mcp/server.mjs)           │');
@@ -242,7 +407,18 @@ function runDoctor(projectDir = process.cwd()) {
   console.log('│                                                             │');
   console.log('└─────────────────────────────────────────────────────────────┘\n');
 
-  return {
+  if (errors.length > 0) {
+    console.error(`[ERROR] Diagnostic check failed with ${errors.length} error(s):`);
+    for (const err of errors) {
+      console.error(`  - ${err}`);
+    }
+    console.error('');
+  }
+
+  const result = {
+    ok,
+    errors,
+    warnings,
     hasAgents,
     nodeOk: nodeCheck.ok,
     activeProfile,
@@ -251,12 +427,22 @@ function runDoctor(projectDir = process.cwd()) {
     hasMcp,
     hookCheck,
     secretCheck,
+    lockfileCheck,
+    adapterCheck,
+    symlinkCheck,
     stack,
   };
+
+  if (options.exitOnError !== false && !ok && require.main === module) {
+    process.exit(1);
+  }
+
+  return result;
 }
 
 if (require.main === module) {
-  runDoctor();
+  const res = runDoctor();
+  if (!res.ok) process.exit(1);
 }
 
 module.exports = {
@@ -265,5 +451,8 @@ module.exports = {
   checkPreCommitHook,
   checkSecretScanner,
   checkCompiledAdapters,
+  checkLockfileIntegrity,
+  checkAdapterIntegrity,
+  checkSymlinks,
   inspectSkills,
 };

package/.agents/generated/claude/skills/engineering-workflow/SKILL.md

@@ -33,7 +33,7 @@ Inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills
 ```
 
 **IRON RULE**: In interactive development, no phase can be skipped and no code is written before `/plan` is approved.  
-**Direct Build Exception**: When the prompt/caller explicitly requests a standalone implementation, or declares `[PHASE: Build]`, execute the BUILD phase directly and deliver the complete, self-contained production code without conversational pauses.
+**Direct Build & Fast-Track Exception**: When the prompt/caller explicitly requests a standalone implementation, declares `[PHASE: Build]`, or requests routine operational/maintenance tasks (git operations, version bumps, typo fixes, small config tweaks, diagnostic checks), proceed directly to execution without conversational approval pauses.
 
 ---
 

package/.agents/generated/claude/skills/gemini-precision/SKILL.md

@@ -82,6 +82,10 @@ Activate whenever:
   - State what was inspected or verified from the code.
   - State the architectural decision made and the immediate next action.
 - Keep narration crisp and actionable without excessive verbosity.
+- **Zero-Spam Constraint**:
+  - ❌ **Forbidden**: Starting every intermediate step, tool call, or status update with domain/phase/role tags (e.g. `[DOMAIN: ...] [PHASE: ...] [ROLE: ...]`).
+  - ✅ **Mandatory**: Declare role and phase strictly once at the start of a phase. Intermediate step updates must be clean, natural language sentences describing technical actions directly.
+  - Do not narrate routine micro-inspections (single line reads or basic greps). Announce only meaningful task phases and decisions.
 
 ---
 

package/.agents/generated/claude/skills/graphify/SKILL.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**Graphify** is a codebase mapping and context optimization engine. Instead of feeding raw directory trees or entire source files into an agent's context window, Graphify leverages local **Tree-sitter** AST parsing to construct a deterministic, queryable knowledge graph (`graph.json`, `GRAPH_REPORT.md`, `graph.html`).
+**Graphify** is an instruction-only codebase mapping and context optimization guide. Instead of feeding raw directory trees or entire source files into an agent's context window, Graphify instructs agents on how to construct a deterministic, queryable knowledge graph (`graph.json`, `GRAPH_REPORT.md`, `graph.html`) using external companion analyzers (such as the TypeScript AST analyzer in `contextos-mcp` or the external `graphifyy` CLI), keeping the core package 100% zero-dependency without bundled native Tree-sitter binaries.
 
 This skill instructs agents how to build, query, and maintain codebase graphs to navigate complex architectures with near-zero token overhead.
 

package/.agents/generated/claude/skills/gstack-roles/SKILL.md

@@ -18,12 +18,14 @@ Inspired by [Garry Tan's gstack](https://github.com/garrytan/gstack) — shippin
 
 ## Role Identification Protocol
 
-At the start of each task, declare your role:
+At the start of each task or major phase switch, declare your role:
 
 ```
 [ROLE: <Role Name>] — <One-line description of your mandate for this task>
 ```
 
+> **Anti-Spam Invariant**: Declare this role **strictly once per phase**. Never prefix intermediate tool calls, file operations, or step updates with role tags.
+
 Then execute ONLY within the constraints of that role.
 
 ---