everything-gemini 0.0.0-stage → 1.0.0

package/bin/everything-gemini

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+
+/**
+ * Everything Antigravity (eagy) CLI
+ * Zero-dependency harness manager for Google Antigravity
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const GLOBAL_CONFIG_DIR = path.join(os.homedir(), '.gemini', 'config');
+const WORKSPACE_DIR = process.cwd();
+const AGENTS_DIR = path.join(WORKSPACE_DIR, '.agents');
+
+// ANSI Colors
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const BLUE = '\x1b[34m';
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const GRAY = '\x1b[90m';
+
+function printBanner() {
+  console.log(`
+${CYAN}${BOLD}🪐 Everything Gemini (${GREEN}everything-gemini${CYAN}) v1.0.0${RESET}
+${GRAY}The open-source agent harness & multi-agent orchestrator for Google Gemini & Antigravity${RESET}
+`);
+}
+
+function printHelp() {
+  printBanner();
+  console.log(`${BOLD}USAGE:${RESET}`);
+  console.log(`  everything-gemini <command> [options]\n`);
+  console.log(`${BOLD}COMMANDS:${RESET}`);
+  console.log(`  ${GREEN}doctor${RESET}                      Inspect system, AGY surfaces, and configuration health`);
+  console.log(`  ${GREEN}install${RESET} [options]           Install eagy profiles into workspace or globally`);
+  console.log(`  ${GREEN}list${RESET}                        Show all available skills, rules, hooks, and plugins`);
+  console.log(`  ${GREEN}new-skill${RESET} <name>            Scaffold a new progressive-disclosure skill`);
+  console.log(`  ${GREEN}new-agent${RESET} <name>            Scaffold a new scoped subagent specification`);
+  console.log(`  ${GREEN}add${RESET} <type> <name>           Add a specific skill, rule, or plugin to workspace`);
+  console.log(`  ${GREEN}validate${RESET}                    Run self-test on frontmatter, JSON schemas & hooks`);
+  console.log(`  ${GREEN}help${RESET}                        Show this help message\n`);
+  console.log(`${BOLD}OPTIONS for 'install':${RESET}`);
+  console.log(`  ${CYAN}--profile <core|developer|full>${RESET}   Installation preset profile (default: developer)`);
+  console.log(`  ${CYAN}--global${RESET}                          Install globally into ~/.gemini/config/`);
+  console.log(`  ${CYAN}--workspace <path>${RESET}                Install into custom workspace directory`);
+  console.log(`  ${CYAN}--force${RESET}                          Overwrite existing configuration files\n`);
+}
+
+function runDoctor() {
+  printBanner();
+  console.log(`${BOLD}🔍 Running Antigravity & Environment Diagnostics...${RESET}\n`);
+
+  let allGood = true;
+
+  // 1. Node.js Version
+  const nodeVersion = process.version;
+  console.log(`  ${GREEN}✔${RESET} Node.js runtime: ${BOLD}${nodeVersion}${RESET}`);
+
+  // 2. Check for Antigravity CLI ('agy')
+  let agyFound = false;
+  try {
+    const agyVer = execSync('agy --version 2>/dev/null || which agy 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (agyVer) {
+      console.log(`  ${GREEN}✔${RESET} Antigravity CLI ('agy'): ${BOLD}${agyVer}${RESET}`);
+      agyFound = true;
+    }
+  } catch (e) {
+    // Not found in path
+  }
+  if (!agyFound) {
+    console.log(`  ${YELLOW}ℹ${RESET} Antigravity CLI ('agy'): ${GRAY}Not found in standard PATH (Desktop 2.0 or IDE may be active)${RESET}`);
+  }
+
+  // 3. Check for Global Gemini Config
+  const hasGlobal = fs.existsSync(GLOBAL_CONFIG_DIR);
+  if (hasGlobal) {
+    console.log(`  ${GREEN}✔${RESET} Global Config Root: ${BOLD}${GLOBAL_CONFIG_DIR}${RESET}`);
+  } else {
+    console.log(`  ${GRAY}○${RESET} Global Config Root: ${GRAY}${GLOBAL_CONFIG_DIR} (Not yet created)${RESET}`);
+  }
+
+  // 4. Check for Workspace .agents
+  const hasWorkspaceAgents = fs.existsSync(AGENTS_DIR);
+  if (hasWorkspaceAgents) {
+    console.log(`  ${GREEN}✔${RESET} Workspace Customizations: ${BOLD}${AGENTS_DIR}${RESET}`);
+  } else {
+    console.log(`  ${GRAY}○${RESET} Workspace Customizations: ${GRAY}No .agents/ directory in current CWD${RESET}`);
+  }
+
+  // 5. Git Status
+  try {
+    execSync('git rev-parse --is-inside-work-tree 2>/dev/null');
+    let gitBranch = 'main';
+    try {
+      gitBranch = execSync('git rev-parse --abbrev-ref HEAD 2>/dev/null', { encoding: 'utf8' }).trim();
+    } catch (e) {
+      gitBranch = 'initial (main)';
+    }
+    console.log(`  ${GREEN}✔${RESET} Git repository detected (${BOLD}${gitBranch}${RESET})`);
+  } catch (e) {
+    console.log(`  ${YELLOW}ℹ${RESET} Current directory is not a git repository`);
+  }
+
+  console.log(`\n${GREEN}${BOLD}Diagnostics completed! Antigravity surfaces are ready.${RESET}\n`);
+}
+
+function listComponents() {
+  printBanner();
+  console.log(`${BOLD}📦 Everything Gemini Catalog:${RESET}\n`);
+
+  
+  // Scoped Subagents
+  console.log(`\n${CYAN}${BOLD}🤖 Scoped Subagents (agents/):${RESET}`);
+  const agentsDir = path.join(REPO_ROOT, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    const agents = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+    for (const ag of agents) {
+      const name = ag.replace('.md', '');
+      console.log(`  ${BOLD}${name.padEnd(24)}${RESET}`);
+    }
+  }
+
+  // Skills
+  console.log(`${CYAN}${BOLD}⚡ Skills (Progressive Disclosure):${RESET}`);
+  const skillsDir = path.join(REPO_ROOT, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    const skills = fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+    for (const skill of skills) {
+      const skillMd = path.join(skillsDir, skill, 'SKILL.md');
+      let desc = 'No description';
+      if (fs.existsSync(skillMd)) {
+        const content = fs.readFileSync(skillMd, 'utf8');
+        const match = content.match(/description:\s*>?-?\s*([^\n\r]+)/);
+        if (match) desc = match[1].trim();
+      }
+      console.log(`  ${BOLD}${skill.padEnd(24)}${RESET} ${GRAY}${desc}${RESET}`);
+    }
+  }
+
+  // Rules
+  console.log(`\n${CYAN}${BOLD}📏 Rules & Guidelines:${RESET}`);
+  const rulesDir = path.join(REPO_ROOT, 'rules');
+  if (fs.existsSync(rulesDir)) {
+    function findRules(dir, prefix = '') {
+      const items = fs.readdirSync(dir, { withFileTypes: true });
+      for (const item of items) {
+        if (item.isDirectory()) {
+          findRules(path.join(dir, item.name), `${prefix}${item.name}/`);
+        } else if (item.name.endsWith('.md')) {
+          console.log(`  ${BOLD}${(prefix + item.name).padEnd(32)}${RESET}`);
+        }
+      }
+    }
+    findRules(rulesDir);
+  }
+
+  // Hooks
+  console.log(`\n${CYAN}${BOLD}🛡️ Lifecycle Hooks:${RESET}`);
+  const hooksDir = path.join(REPO_ROOT, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    const hooks = fs.readdirSync(hooksDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+    for (const hook of hooks) {
+      console.log(`  ${BOLD}${hook.padEnd(24)}${RESET}`);
+    }
+  }
+
+  // Plugins
+  console.log(`\n${CYAN}${BOLD}🔌 Domain Plugins:${RESET}`);
+  const pluginsDir = path.join(REPO_ROOT, 'plugins');
+  if (fs.existsSync(pluginsDir)) {
+    const plugins = fs.readdirSync(pluginsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+    for (const plugin of plugins) {
+      const pJson = path.join(pluginsDir, plugin, 'plugin.json');
+      let name = plugin;
+      if (fs.existsSync(pJson)) {
+        try {
+          const parsed = JSON.parse(fs.readFileSync(pJson, 'utf8'));
+          if (parsed.name) name = parsed.name;
+        } catch (e) {}
+      }
+      console.log(`  ${BOLD}${plugin.padEnd(24)}${RESET} ${GRAY}(${name})${RESET}`);
+    }
+  }
+  console.log('');
+}
+
+function copyRecursiveSync(src, dest) {
+  const exists = fs.existsSync(src);
+  const stats = exists && fs.statSync(src);
+  const isDirectory = exists && stats.isDirectory();
+  if (isDirectory) {
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    fs.readdirSync(src).forEach(childItemName => {
+      copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName));
+    });
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function installProfile(profile = 'developer', isGlobal = false, customTarget = null) {
+  printBanner();
+  const targetDir = customTarget 
+    ? path.resolve(customTarget)
+    : (isGlobal ? GLOBAL_CONFIG_DIR : AGENTS_DIR);
+
+  console.log(`${BOLD}🚀 Installing eagy Profile: [${GREEN}${profile}${RESET}${BOLD}]${RESET}`);
+  console.log(`Target Directory: ${CYAN}${targetDir}${RESET}\n`);
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Ensure subdirectories exist
+  const targetSkills = path.join(targetDir, 'skills');
+  const targetRules = path.join(targetDir, 'rules');
+  const targetPlugins = path.join(targetDir, 'plugins');
+  fs.mkdirSync(targetSkills, { recursive: true });
+  fs.mkdirSync(targetRules, { recursive: true });
+  fs.mkdirSync(targetPlugins, { recursive: true });
+
+  const skillsSrc = path.join(REPO_ROOT, 'skills');
+  const rulesSrc = path.join(REPO_ROOT, 'rules');
+  const hooksSrc = path.join(REPO_ROOT, 'hooks');
+  const pluginsSrc = path.join(REPO_ROOT, 'plugins');
+
+  // Copy Common Base Rules
+  const commonGemini = path.join(rulesSrc, 'common', 'GEMINI.md');
+  const commonAgents = path.join(rulesSrc, 'common', 'AGENTS.md');
+  if (fs.existsSync(commonGemini)) {
+    fs.copyFileSync(commonGemini, path.join(targetDir, 'GEMINI.md'));
+    console.log(`  ${GREEN}✔${RESET} Installed base GEMINI.md`);
+  }
+  if (fs.existsSync(commonAgents)) {
+    fs.copyFileSync(commonAgents, path.join(targetDir, 'AGENTS.md'));
+    console.log(`  ${GREEN}✔${RESET} Installed base AGENTS.md`);
+  }
+
+  // Determine what to copy based on profile
+  if (profile === 'core' || profile === 'developer' || profile === 'full') {
+    // Core Skills
+    const coreSkills = ['tdd-workflow', 'repo-onboarding'];
+    for (const s of coreSkills) {
+      const src = path.join(skillsSrc, s);
+      if (fs.existsSync(src)) {
+        copyRecursiveSync(src, path.join(targetSkills, s));
+        console.log(`  ${GREEN}✔${RESET} Installed skill: ${s}`);
+      }
+    }
+    // Core Hook (Safety Shield)
+    const safetyHookJson = path.join(hooksSrc, 'safety-shield', 'hooks.json');
+    if (fs.existsSync(safetyHookJson)) {
+      copyRecursiveSync(path.join(hooksSrc, 'safety-shield'), path.join(targetDir, 'hooks', 'safety-shield'));
+      console.log(`  ${GREEN}✔${RESET} Installed safety-shield hook`);
+    }
+  }
+
+  if (profile === 'developer' || profile === 'full') {
+    // Developer Skills
+    const devSkills = ['browser-qa-tester', 'architecture-designer', 'git-craftsman', 'performance-profiler', 'fullstack-nextjs'];
+    for (const s of devSkills) {
+      const src = path.join(skillsSrc, s);
+      if (fs.existsSync(src)) {
+        copyRecursiveSync(src, path.join(targetSkills, s));
+        console.log(`  ${GREEN}✔${RESET} Installed skill: ${s}`);
+      }
+    }
+
+    // Developer Language Rules
+    const langRules = path.join(rulesSrc, 'languages');
+    if (fs.existsSync(langRules)) {
+      copyRecursiveSync(langRules, targetRules);
+      console.log(`  ${GREEN}✔${RESET} Installed language rules (TypeScript, Python, Go)`);
+    }
+
+    // Auto-lint formatter hook
+    const lintHook = path.join(hooksSrc, 'auto-lint-formatter');
+    if (fs.existsSync(lintHook)) {
+      copyRecursiveSync(lintHook, path.join(targetDir, 'hooks', 'auto-lint-formatter'));
+      console.log(`  ${GREEN}✔${RESET} Installed auto-lint-formatter hook`);
+    }
+
+    // Developer Plugins
+    const devPlugins = ['web-fullstack', 'python-ai'];
+    for (const p of devPlugins) {
+      const src = path.join(pluginsSrc, p);
+      if (fs.existsSync(src)) {
+        copyRecursiveSync(src, path.join(targetPlugins, p));
+        console.log(`  ${GREEN}✔${RESET} Installed plugin: ${p}`);
+      }
+    }
+  }
+
+  if (profile === 'full') {
+    // All Skills
+    copyRecursiveSync(skillsSrc, targetSkills);
+    console.log(`  ${GREEN}✔${RESET} Installed entire skills library`);
+
+    // All Rules
+    copyRecursiveSync(rulesSrc, targetRules);
+    console.log(`  ${GREEN}✔${RESET} Installed entire rules library`);
+
+    // All Plugins
+    copyRecursiveSync(pluginsSrc, targetPlugins);
+    console.log(`  ${GREEN}✔${RESET} Installed all modular plugins`);
+
+    // All Hooks
+    copyRecursiveSync(hooksSrc, path.join(targetDir, 'hooks'));
+    console.log(`  ${GREEN}✔${RESET} Installed full lifecycle hooks suite`);
+
+    // MCP Config Example
+    const mcpExample = path.join(REPO_ROOT, 'mcp', 'mcp_config.example.json');
+    if (fs.existsSync(mcpExample)) {
+      fs.copyFileSync(mcpExample, path.join(targetDir, 'mcp_config.json'));
+      console.log(`  ${GREEN}✔${RESET} Installed mcp_config.json`);
+    }
+  }
+
+  // Create or Merge Master hooks.json in targetDir
+  const masterHooks = {
+    "safety-shield": {
+      "PreToolUse": [
+        {
+          "matcher": "run_command",
+          "hooks": [
+            {
+              "type": "command",
+              "command": "bash ./hooks/safety-shield/scripts/safety-gate.sh",
+              "timeout": 15
+            }
+          ]
+        }
+      ]
+    }
+  };
+  fs.writeFileSync(path.join(targetDir, 'hooks.json'), JSON.stringify(masterHooks, null, 2));
+  console.log(`  ${GREEN}✔${RESET} Generated master hooks.json`);
+
+  console.log(`\n${GREEN}${BOLD}🎉 Installation complete! Everything Gemini is active.${RESET}\n`);
+}
+
+function runValidate() {
+  printBanner();
+  console.log(`${BOLD}🧪 Validating everything-gemini components...${RESET}\n`);
+  try {
+    const validateScript = path.join(REPO_ROOT, 'scripts', 'validate.sh');
+    execSync(`bash "${validateScript}"`, { stdio: 'inherit' });
+  } catch (err) {
+    console.error(`\n${RED}Validation failed.${RESET}`);
+    process.exit(1);
+  }
+}
+
+function scaffoldSkill(name) {
+  if (!name) {
+    console.error(`${RED}Error: Skill name required. Example: everything-gemini new-skill my-skill${RESET}`);
+    process.exit(1);
+  }
+  const cleanName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+  const targetDir = path.join(REPO_ROOT, 'skills', cleanName);
+  if (fs.existsSync(targetDir)) {
+    console.error(`${RED}Error: Skill '${cleanName}' already exists at ${targetDir}${RESET}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(path.join(targetDir, 'references'), { recursive: true });
+  fs.mkdirSync(path.join(targetDir, 'scripts'), { recursive: true });
+
+  const titleCase = cleanName.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ');
+  const skillMd = `---
+name: ${cleanName}
+description: >-
+  Use this skill when ... (describe triggering conditions in third person).
+---
+
+# ${titleCase}
+
+## Overview
+Provide a concise overview of what this skill achieves and when it is invoked.
+
+## Progressive Disclosure Architecture
+- Keep this main \`SKILL.md\` focused on procedural step-by-step instructions.
+- Put deep technical documentation and schemas in [references/spec.md](./references/spec.md).
+- Place deterministic automation or verification scripts in [scripts/](./scripts/).
+
+## Procedural Workflow
+1. **Analyze Requirements**: Inspect the target environment and configuration.
+2. **Execute Actions**: Run necessary tasks sequentially.
+3. **Verify Outcome**: Run validation checks.
+
+## Verification Checklist
+- [ ] Task completed with zero side-effects
+- [ ] Tests and linters pass cleanly
+`;
+
+  const specMd = `# Reference Documentation for ${cleanName}
+
+Detailed architecture, API contracts, edge cases, and background reference material.
+`;
+
+  const helperSh = `#!/usr/bin/env bash
+set -euo pipefail
+
+# Helper script for ${cleanName}
+echo "Executing ${cleanName} automated helper..."
+`;
+
+  fs.writeFileSync(path.join(targetDir, 'SKILL.md'), skillMd);
+  fs.writeFileSync(path.join(targetDir, 'references', 'spec.md'), specMd);
+  const scriptPath = path.join(targetDir, 'scripts', 'helper.sh');
+  fs.writeFileSync(scriptPath, helperSh);
+  try { fs.chmodSync(scriptPath, 0o755); } catch (e) {}
+
+  console.log(`${GREEN}✔ Created progressive disclosure skill:${RESET} ${BOLD}${cleanName}${RESET}`);
+  console.log(`  📁 ${targetDir}`);
+  console.log(`  📄 SKILL.md (YAML frontmatter + procedural workflow)`);
+  console.log(`  📄 references/spec.md (progressive reference docs)`);
+  console.log(`  🔧 scripts/helper.sh (executable helper)\n`);
+}
+
+function scaffoldAgent(name) {
+  if (!name) {
+    console.error(`${RED}Error: Agent name required. Example: everything-gemini new-agent my-agent${RESET}`);
+    process.exit(1);
+  }
+  const cleanName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+  const targetDir = path.join(REPO_ROOT, 'agents');
+  if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+  const targetFile = path.join(targetDir, `${cleanName}.md`);
+  if (fs.existsSync(targetFile)) {
+    console.error(`${RED}Error: Agent '${cleanName}' already exists at ${targetFile}${RESET}`);
+    process.exit(1);
+  }
+
+  const titleCase = cleanName.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(' ');
+  const agentMd = `# Subagent: ${titleCase}
+
+## Role & Mission
+Describe the specific purpose and focus area of this subagent.
+
+## Permitted Tools & Scope
+- **Allowed Tools**: (e.g. view_file, grep_search, run_command)
+- **Restricted Tools**: (e.g. no destructive file overwrites or network calls)
+
+## Operating Principles
+1. **Surgical Precision**: Focus exclusively on the delegated objective.
+2. **Context Efficiency**: Keep intermediate reasoning concise and return structured findings.
+3. **Deterministic Verification**: Verify all claims with code evidence before reporting.
+
+## Handoff & Synthesis
+Return structured report to parent agent:
+- **Findings / Actions Taken**:
+- **Modified Files**:
+- **Open Questions / Recommended Next Steps**:
+`;
+
+  fs.writeFileSync(targetFile, agentMd);
+  console.log(`${GREEN}✔ Created subagent profile:${RESET} ${BOLD}${cleanName}${RESET}`);
+  console.log(`  📄 ${targetFile}\n`);
+}
+
+// CLI Argument Parsing
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+
+switch (command) {
+  case 'doctor':
+    runDoctor();
+    break;
+  case 'list':
+    listComponents();
+    break;
+  case 'new-skill':
+    scaffoldSkill(args[1]);
+    break;
+  case 'new-agent':
+    scaffoldAgent(args[1]);
+    break;
+  case 'install': {
+    let profile = 'developer';
+    let isGlobal = false;
+    let customTarget = null;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === '--profile' && args[i + 1]) profile = args[++i];
+      else if (args[i] === '--global') isGlobal = true;
+      else if (args[i] === '--workspace' && args[i + 1]) customTarget = args[++i];
+    }
+    installProfile(profile, isGlobal, customTarget);
+    break;
+  }
+  case 'validate':
+    runValidate();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  default:
+    printHelp();
+    break;
+}
+

package/docs/architecture/cortex-loop.md

@@ -0,0 +1,57 @@
+# The Cortex Execution Loop & Reactive Wakeup
+
+At the core of Google Antigravity is **Cortex**, an asynchronous, event-driven agent runtime designed to eliminate busy-waiting, minimize token latency, and reliably coordinate tools and subagents.
+
+---
+
+## 1. Traditional Agents vs. Antigravity Cortex
+
+```
+[Traditional Agent Loop]
+Prompt -> Model -> Tool Call -> Busy-Poll / Sleep Loop -> Read stdout -> Model (Repeats)
+Problem: Burns CPU cycles, wastes tokens on polling messages, times out easily.
+
+[Antigravity Cortex Loop]
+Prompt -> Model -> Tool Call Launched (Async) -> Cortex Suspends Turn
+         ^                                              |
+         |=== Wakeup Event (Process Finished / Timer) ==|
+```
+
+In Antigravity:
+1. **Async by Default**: Tools such as `run_command` or background tasks return immediately if long-running.
+2. **Reactive Wakeup**: When a background process terminates or writes output, or when a scheduled timer fires, the system automatically resumes the agent turn with the complete message payload.
+3. **Zero Polling**: Agents are instructed never to run loops or poll status endpoints.
+
+---
+
+## 2. The Five Lifecycle Hook Stages
+
+Cortex exposes five deterministic interception points for custom code:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant U as User / Turn
+    participant PreI as PreInvocation Hook
+    participant M as Gemini Model
+    participant PostI as PostInvocation Hook
+    participant PreT as PreToolUse Hook
+    participant Tool as Tool / Sandbox
+    participant PostT as PostToolUse Hook
+    participant S as Stop Hook
+
+    U->>PreI: Turn Triggered
+    PreI-->>M: Context Injected (ephemeralMessage)
+    M->>PostI: Model Generates Actions / Text
+    PostI-->>M: Continue or Terminate?
+    alt Tool Called
+        M->>PreT: Inspect Tool Call
+        PreT-->>Tool: Allow / Deny / Ask / Overwrite
+        Tool->>PostT: Output / Error
+        PostT-->>M: Clean up / Lint
+    end
+    M->>S: Model Decides to Stop
+    S-->>U: Verify Goal (Allow Stop or Continue)
+```
+
+Each stage communicates over standard `stdin` and `stdout` using protojson camelCase structures.

package/docs/architecture/memory-and-context.md

@@ -0,0 +1,50 @@
+# Memory & Context Architecture
+
+Antigravity employs a three-tier memory model to balance long-term project recall, immediate trajectory history, and structured user-facing reporting:
+
+```
++---------------------------------------------------------------------------------+
+|                                 ANTIGRAVITY MEMORY                              |
++--------------------------+------------------------------+-----------------------+
+| 1. Knowledge Items (KI)  | 2. Dual Transcripts          | 3. Brain Artifacts    |
+| (Persistent Architecture)| (Execution Trajectory)       | (Structured Output)   |
++--------------------------+------------------------------+-----------------------+
+| - Stored in              | - transcript.jsonl (Compact) | - Markdown files in   |
+|   <appDataDir>/knowledge | - transcript_full.jsonl      |   <appDataDir>/brain/ |
+| - metadata.json +        |   (Untruncated)              | - Alerts, Mermaid,    |
+|   artifacts/             | - Keyed by Conversation ID   |   Tables, Carousels,  |
+| - Checked before         | - Token-efficient recall     |   Live Diff blocks    |
+|   research               |                              |                       |
++--------------------------+------------------------------+-----------------------+
+```
+
+---
+
+## 1. Knowledge Items (KI)
+
+**Knowledge Items** capture curated, localized context about specific repositories.
+- **Location**: `<appDataDir>/knowledge/<ki-id>/`
+- **Contents**:
+  - `metadata.json`: Summary, timestamps, and references to original source files.
+  - `artifacts/`: Related architecture blueprints, setup instructions, and known bug gotchas.
+- **Mandatory Agent Rule**: Antigravity agents check KI summaries *before* performing redundant codebase research.
+
+---
+
+## 2. Dual Transcripts
+
+Every Antigravity conversation produces two parallel chronological logs in JSON Lines (`.jsonl`) format under `<appDataDir>/brain/<conversation-id>/.system_generated/logs`:
+
+1. **`transcript.jsonl`**: Token-efficient version where very large outputs (such as massive grep results or lengthy terminal logs) are truncated. Ideal for rapid history search and recalling earlier steps.
+2. **`transcript_full.jsonl`**: The untruncated record containing verbatim outputs for deep debugging.
+
+---
+
+## 3. Brain Artifacts
+
+Rather than flooding the user chat with 500-line code blocks or raw terminal dumps, Antigravity renders **Artifacts** stored in `<appDataDir>/brain/<conversation-id>/`:
+- **Alert Callouts**: `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`.
+- **Mermaid Diagrams**: System architectures, sequence diagrams, and class structures.
+- **Diff Blocks**: Clean visual before/after changes.
+- **Carousels**: Four-backtick (````carousel ... ````) interactive slides.
+- **Media Embeds**: Embedded WebP recordings from `browser_subagent` and image assets (`![caption](/path/to/media.webp)`).

package/docs/architecture/progressive-disclosure.md

@@ -0,0 +1,41 @@
+# Progressive Disclosure in Antigravity
+
+One of the greatest bottlenecks in modern agentic coding is **prompt bloat**. When an agent harness attempts to inject 50 different rules, 30 different stack guides, and full documentation on every single turn, it degrades the model's instruction-following accuracy and consumes tens of thousands of tokens per turn.
+
+Antigravity solves this with **Progressive Disclosure**.
+
+---
+
+## 1. How Progressive Disclosure Works
+
+Instead of injecting entire skill files (`SKILL.md`) into the system prompt:
+1. **Metadata-Only Injection**: Only the `name` and `description` from the YAML frontmatter are provided to the model in the system prompt.
+2. **Intent Recognition**: When a user's prompt or subtask matches a skill's description, the model proactively reads the complete `SKILL.md` using `view_file`.
+3. **Subdocument Linking**: Inside `SKILL.md`, bulky references are stored in `references/` or `examples/`, which are only fetched if specific edge-case guidance is required.
+
+---
+
+## 2. Comparative Token Consumption
+
+```
++------------------------------------+--------------------------+
+| Harness Strategy                   | Baseline Prompt Overhead |
++------------------------------------+--------------------------+
+| Monolithic Prompts (e.g. naive)    | ~48,000 tokens / turn    |
+| eagy Progressive Disclosure        | ~3,200 tokens / turn     |
++------------------------------------+--------------------------+
+| Net Token Savings                  | 85% - 93%                |
++------------------------------------+--------------------------+
+```
+
+---
+
+## 3. Best Practices for Writing Skills
+
+1. **Third-Person Triggers**: Write descriptions in third-person stating *what* the skill does and *when* to invoke it:
+   ```yaml
+   description: >-
+     Enforces strict Test-Driven Development (Red-Green-Refactor). Use this skill when the user asks to implement a new feature, fix a bug, or refactor logic using TDD.
+   ```
+2. **Lean Instructions**: Keep the root `SKILL.md` concise (< 200 lines).
+3. **Move Bulky Tables to `references/`**: Link them via standard Markdown links (`[patterns.md](./references/patterns.md)`).