contextos-agents 1.6.0 → 1.7.0

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.
 
 ---

package/.agents/generated/claude/skills/subagent-orchestrator/SKILL.md

@@ -37,6 +37,22 @@ Before delegating any subagent task:
 
 ### 3. Context Hand-off Specification
 
+Every subagent dispatch must be backed by an immutable `TaskBrief`:
+
+```ts
+type TaskBrief = Readonly<{
+  taskId: string;
+  baseSha: string;
+  objective: string;
+  writeScope: readonly string[];
+  testCommand: string;
+  expectedResult: string;
+  maxAttempts: number;
+}>;
+```
+
+Create the brief once before dispatch. Agents and retry loops must reuse it without
+changing the base commit, scope, verification command, or acceptance result.
 Every subagent dispatch prompt must contain:
 
 1. **Target Objective**: Single, verifiable deliverable.
@@ -72,6 +88,7 @@ Every subagent dispatch prompt must contain:
 ## Validation Checklist
 
 - [ ] All delegated tasks have disjoint, non-overlapping file sets.
+- [ ] Every worker received an immutable `TaskBrief` tied to the original `baseSha`.
 - [ ] Every subagent prompt has explicit read vs write boundaries.
 - [ ] Subagent results verified individually before merging.
 - [ ] Global regression suite executed across the entire repository after all subagents finish.

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

@@ -38,7 +38,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/gemini/skills/gemini-precision/SKILL.md

@@ -87,6 +87,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/gemini/skills/graphify/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: graphify
 description: >
-  Codebase knowledge graph generator via Tree-sitter AST parsing and semantic indexing. Minimizes token consumption and maps dependency blast radius.
+  Codebase knowledge graph generator and architecture mapping guide. Instructs agents on AST dependency extraction and blast radius analysis.
 ---
 # graphify
 
 ## 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/gemini/skills/gstack-roles/SKILL.md

@@ -23,12 +23,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.
 
 ---

package/.agents/generated/gemini/skills/subagent-orchestrator/SKILL.md

@@ -42,6 +42,22 @@ Before delegating any subagent task:
 
 ### 3. Context Hand-off Specification
 
+Every subagent dispatch must be backed by an immutable `TaskBrief`:
+
+```ts
+type TaskBrief = Readonly<{
+  taskId: string;
+  baseSha: string;
+  objective: string;
+  writeScope: readonly string[];
+  testCommand: string;
+  expectedResult: string;
+  maxAttempts: number;
+}>;
+```
+
+Create the brief once before dispatch. Agents and retry loops must reuse it without
+changing the base commit, scope, verification command, or acceptance result.
 Every subagent dispatch prompt must contain:
 
 1. **Target Objective**: Single, verifiable deliverable.
@@ -77,6 +93,7 @@ Every subagent dispatch prompt must contain:
 ## Validation Checklist
 
 - [ ] All delegated tasks have disjoint, non-overlapping file sets.
+- [ ] Every worker received an immutable `TaskBrief` tied to the original `baseSha`.
 - [ ] Every subagent prompt has explicit read vs write boundaries.
 - [ ] Subagent results verified individually before merging.
 - [ ] Global regression suite executed across the entire repository after all subagents finish.

package/.agents/plugins/contextos/hooks.json

@@ -0,0 +1,25 @@
+{
+  "contextos-session-guard": {
+    "enabled": true,
+    "PreInvocation": [
+      {
+        "type": "command",
+        "command": "node .agents/ctx.js doctor"
+      }
+    ]
+  },
+  "contextos-integrity-check": {
+    "enabled": true,
+    "PostToolUse": [
+      {
+        "matcher": "run_command",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .agents/ctx.js validate"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.agents/plugins/contextos/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "contextos",
+  "version": "1.7.0",
+  "description": "Deterministic AI Project Operating System context compiler, MCP runtime, and high-precision engineering skills for Antigravity.",
+  "author": {
+    "name": "ContextOS Team",
+    "url": "https://github.com/kok-o/contextos-agents"
+  },
+  "repository": "https://github.com/kok-o/contextos-agents",
+  "license": "MIT",
+  "keywords": [
+    "contextos",
+    "antigravity",
+    "agent-skills",
+    "orchestration",
+    "gemini",
+    "engineering-workflow"
+  ]
+}

package/.agents/plugins.js

@@ -36,6 +36,17 @@ const REGISTRY_URL   = 'https://raw.githubusercontent.com/kok-o/contextos-agents
 const MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024;
 const SAFE_SKILL_NAME = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+const NO_COLOR = process.env.NO_COLOR || !process.stdout.isTTY;
+const c = {
+  green:  (s) => NO_COLOR ? s : `\x1b[32m${s}\x1b[0m`,
+  red:    (s) => NO_COLOR ? s : `\x1b[31m${s}\x1b[0m`,
+  yellow: (s) => NO_COLOR ? s : `\x1b[33m${s}\x1b[0m`,
+  cyan:   (s) => NO_COLOR ? s : `\x1b[36m${s}\x1b[0m`,
+  bold:   (s) => NO_COLOR ? s : `\x1b[1m${s}\x1b[0m`,
+  dim:    (s) => NO_COLOR ? s : `\x1b[2m${s}\x1b[0m`,
+};
+
 // ── Prompt Injection Scanner ──────────────────────────────────────────────────
 const PROMPT_INJECTION_PATTERNS = [
   /ignore\s+(all\s+)?previous\s+instructions/i,
@@ -48,6 +59,18 @@ const PROMPT_INJECTION_PATTERNS = [
   /\b(?:eval|exec|Function)\s*\(/i,
 ];
 
+// ── Shell Escapes & Script Injection Scanner ──────────────────────────────────
+const SHELL_ESCAPE_PATTERNS = [
+  /(?:curl|wget)\s+[^|\n\r]+?\|\s*(?:bash|sh|zsh|powershell|pwsh|cmd)/i,
+  /\bpowershell(?:\.exe)?\s+.*-(?:enc|encodedcommand|ep\s+bypass)\b/i,
+  /\b(?:rm\s+-rf\s+[\/~]|del\s+\/[sfq]\s+[c-z]:[\\\/])/i,
+  /\b(?:mkfifo|mknod)\s+.*?;/i,
+  /\b(?:nc|netcat|ncat)\s+-[elp]+/i,
+  /<script\b[^>]*>[\s\S]*?<\/script>/i,
+  /javascript\s*:\s*[^\s'"]+/i,
+  /data:text\/html/i,
+];
+
 function scanForPromptInjection(content, options = {}) {
   if (typeof content !== 'string') return false;
   const found = PROMPT_INJECTION_PATTERNS.filter(p => p.test(content));
@@ -62,16 +85,124 @@ function scanForPromptInjection(content, options = {}) {
   return false;
 }
 
-// ── ANSI helpers ──────────────────────────────────────────────────────────────
-const NO_COLOR = process.env.NO_COLOR || !process.stdout.isTTY;
-const c = {
-  green:  (s) => NO_COLOR ? s : `\x1b[32m${s}\x1b[0m`,
-  red:    (s) => NO_COLOR ? s : `\x1b[31m${s}\x1b[0m`,
-  yellow: (s) => NO_COLOR ? s : `\x1b[33m${s}\x1b[0m`,
-  cyan:   (s) => NO_COLOR ? s : `\x1b[36m${s}\x1b[0m`,
-  bold:   (s) => NO_COLOR ? s : `\x1b[1m${s}\x1b[0m`,
-  dim:    (s) => NO_COLOR ? s : `\x1b[2m${s}\x1b[0m`,
-};
+function scanContentSecurity(content, filePath, options = {}) {
+  if (typeof content !== 'string') return false;
+
+  const injectionMatches = PROMPT_INJECTION_PATTERNS.filter(p => p.test(content));
+  const shellMatches = SHELL_ESCAPE_PATTERNS.filter(p => p.test(content));
+
+  const allMatches = [
+    ...injectionMatches.map(p => `prompt_injection: ${p.source}`),
+    ...shellMatches.map(p => `shell_or_script: ${p.source}`),
+  ];
+
+  if (allMatches.length > 0) {
+    const rel = filePath ? path.basename(filePath) : 'content';
+    console.warn(c.red(`  🚨 Unsafe pattern or injection detected in plugin file '${rel}':`));
+    console.warn(c.yellow(`     Matches: ${allMatches.join('; ')}`));
+    if (options.throwOnMatch) {
+      throw new Error(`Security validation failed: unsafe content or script injection detected in '${rel}' (${allMatches.length} pattern matches). Installation aborted. Pass --force-unsafe-prompts to override.`);
+    }
+    return true;
+  }
+  return false;
+}
+
+function isScannableFile(fileName) {
+  const ext = path.extname(fileName).toLowerCase();
+  const scannableExtensions = new Set([
+    '.md', '.mdc', '.markdown', '.txt',
+    '.yaml', '.yml', '.json',
+    '.sh', '.bash', '.zsh', '.ps1', '.bat', '.cmd',
+    '.js', '.ts', '.mjs', '.cjs', '.py',
+  ]);
+  return scannableExtensions.has(ext) || !ext;
+}
+
+/**
+ * Recursively scan an entire plugin directory tree:
+ * - Rejects any symlinks that traverse outside the plugin directory
+ * - Scans all documentation and code files (EXAMPLES.md, TROUBLESHOOTING.md, references/, etc.)
+ *   for prompt injection, script injection, and dangerous shell escape patterns.
+ */
+function scanPluginDirectory(pluginDir, options = {}) {
+  const throwOnMatch = options.throwOnMatch !== undefined ? options.throwOnMatch : !options.forceUnsafe;
+  if (!fs.existsSync(pluginDir)) return true;
+
+  const realPluginDir = fs.realpathSync(pluginDir);
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir);
+    } catch {
+      return;
+    }
+
+    for (const name of entries) {
+      const fullPath = path.join(currentDir, name);
+      let lstat;
+      try {
+        lstat = fs.lstatSync(fullPath);
+      } catch {
+        continue;
+      }
+
+      // 1. Check symlink traversal
+      if (lstat.isSymbolicLink()) {
+        let linkTarget;
+        try {
+          linkTarget = fs.readlinkSync(fullPath);
+        } catch (e) {
+          throw new Error(`Security validation failed: Unreadable symlink '${name}'. Installation aborted.`);
+        }
+
+        const resolvedTarget = path.resolve(currentDir, linkTarget);
+        let realTarget;
+        try {
+          realTarget = fs.realpathSync(resolvedTarget);
+        } catch {
+          realTarget = resolvedTarget;
+        }
+
+        const normalizedRealPlugin = realPluginDir.replace(/\\/g, '/').toLowerCase();
+        const normalizedRealTarget = realTarget.replace(/\\/g, '/').toLowerCase();
+
+        if (
+          !normalizedRealTarget.startsWith(normalizedRealPlugin + '/') &&
+          normalizedRealTarget !== normalizedRealPlugin
+        ) {
+          throw new Error(
+            `Security validation failed: Symlink traversal detected in '${name}' pointing outside plugin directory to '${linkTarget}'. Installation aborted.`
+          );
+        }
+      }
+
+      // 2. Walk subdirectories
+      if (lstat.isDirectory()) {
+        if (name === '.git' || name === 'node_modules') continue;
+        walk(fullPath);
+      } else if (lstat.isFile()) {
+        if (name === '.source') continue;
+        if (lstat.size > 2 * 1024 * 1024) continue;
+
+        if (isScannableFile(name)) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf8');
+            scanContentSecurity(content, fullPath, { throwOnMatch });
+          } catch (err) {
+            if (err.message && err.message.startsWith('Security validation failed')) {
+              throw err;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  walk(pluginDir);
+  return true;
+}
 
 // ── plugins.json lock file ─────────────────────────────────────────────────────
 function readLock() {
@@ -232,6 +363,14 @@ async function installFromGitHub(descriptor, skillName, dryRun, checksum, forceU
     fs.writeFileSync(path.join(targetDir, 'skill.yaml'), yamlContent);
   }
 
+  // Deep security scan before writing source marker
+  try {
+    scanPluginDirectory(targetDir, { throwOnMatch: !forceUnsafe, forceUnsafe });
+  } catch (err) {
+    fs.rmSync(targetDir, { recursive: true, force: true });
+    throw err;
+  }
+
   // Write a source marker so we know where to update from
   fs.writeFileSync(path.join(targetDir, '.source'), JSON.stringify({
     type:    'github',
@@ -286,7 +425,8 @@ function installFromNpm(descriptor, skillName, dryRun, checksum, forceUnsafe = f
     if (checksum && sha256.toLowerCase() !== checksum.toLowerCase()) {
       throw new Error(`Checksum mismatch for ${skillName}: expected ${checksum}, got ${sha256}`);
     }
-    scanForPromptInjection(skillMdContent, { throwOnMatch: !forceUnsafe });
+    // Deep security scan across all plugin files (EXAMPLES.md, TROUBLESHOOTING.md, references/, symlinks)
+    scanPluginDirectory(skillSrc, { throwOnMatch: !forceUnsafe, forceUnsafe });
 
     const targetDir = path.join(PLUGINS_DIR, skillName);
     fs.rmSync(targetDir, { recursive: true, force: true });
@@ -546,22 +686,39 @@ async function search(query) {
  * both core (builtin) and plugins.
  * Adapters call this instead of reading CORE_SKILLS directly.
  */
-function collectAllSkillDirs() {
+function collectAllSkillDirs(targetRoot) {
+  const root = targetRoot || process.cwd();
+  const agentsDir = path.join(root, '.agents');
+  const localCore = path.join(agentsDir, 'core', 'skills');
+  const localPlugins = path.join(agentsDir, 'plugins');
+
+  const coreDir = fs.existsSync(localCore) ? localCore : CORE_SKILLS;
+  const pluginsDir = fs.existsSync(localPlugins) ? localPlugins : PLUGINS_DIR;
   const dirs = [];
 
   // Core skills
-  if (fs.existsSync(CORE_SKILLS)) {
-    for (const name of fs.readdirSync(CORE_SKILLS)) {
-      const d = path.join(CORE_SKILLS, name);
+  if (fs.existsSync(coreDir)) {
+    for (const name of fs.readdirSync(coreDir)) {
+      const d = path.join(coreDir, name);
       if (fs.statSync(d).isDirectory()) dirs.push(d);
     }
   }
 
-  // Plugin skills
-  if (fs.existsSync(PLUGINS_DIR)) {
-    for (const name of fs.readdirSync(PLUGINS_DIR)) {
-      const d = path.join(PLUGINS_DIR, name);
-      if (fs.statSync(d).isDirectory()) dirs.push(d);
+  // Plugin skills (supports both standalone skill dirs and plugin bundles with skills/)
+  if (fs.existsSync(pluginsDir)) {
+    for (const name of fs.readdirSync(pluginsDir)) {
+      const d = path.join(pluginsDir, name);
+      if (!fs.statSync(d).isDirectory()) continue;
+
+      const nestedSkills = path.join(d, 'skills');
+      if (fs.existsSync(nestedSkills) && fs.statSync(nestedSkills).isDirectory()) {
+        for (const sub of fs.readdirSync(nestedSkills)) {
+          const subDir = path.join(nestedSkills, sub);
+          if (fs.statSync(subDir).isDirectory()) dirs.push(subDir);
+        }
+      } else if (fs.existsSync(path.join(d, 'SKILL.md')) || fs.existsSync(path.join(d, 'skill.yaml'))) {
+        dirs.push(d);
+      }
     }
   }
 
@@ -579,6 +736,9 @@ module.exports = {
   deriveSkillName,
   isSafeSkillName,
   scanForPromptInjection,
+  scanContentSecurity,
+  scanPluginDirectory,
   PROMPT_INJECTION_PATTERNS,
+  SHELL_ESCAPE_PATTERNS,
   PLUGINS_DIR,
 };

package/.agents/profiles.js

@@ -72,10 +72,34 @@ function parseYamlProfile(text) {
       .filter(Boolean);
   }
 
+  function parseMap(field) {
+    const blockRegex = new RegExp(`^${field}:\\s*\\n((?:[ \\t]+[a-zA-Z0-9_-]+:[^\\n]*\\n?)+)`, 'm');
+    const match = text.match(blockRegex);
+    if (!match) return {};
+    const map = {};
+    const lines = match[1].split('\n');
+    for (const line of lines) {
+      const lineClean = line.replace(/#.*$/, '').trim();
+      if (!lineClean) continue;
+      const kv = lineClean.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+      if (kv) {
+        const key = kv[1].trim();
+        let val = kv[2].trim().replace(/^['"]|['"]$/g, '');
+        if (val === 'true') val = true;
+        else if (val === 'false') val = false;
+        else if (/^\d+$/.test(val)) val = parseInt(val, 10);
+        map[key] = val;
+      }
+    }
+    return map;
+  }
+
   result.prefer_skills = parseList('prefer_skills');
   result.exclude_skills = parseList('exclude_skills');
   result.generate_docs = parseList('generate_docs');
   result.skip_docs = parseList('skip_docs');
+  result.enforce = parseMap('enforce');
+  result.defaults = parseMap('defaults');
 
   return result;
 }
@@ -140,6 +164,8 @@ function applyProfile(profileName, projectDir = process.cwd()) {
     description: profile.description,
     exclude_skills: profile.exclude_skills || [],
     prefer_skills: profile.prefer_skills || [],
+    enforce: profile.enforce || {},
+    defaults: profile.defaults || {},
     appliedAt: new Date().toISOString(),
   };