ag-cortex 0.1.0

package/.agent/workflows/xcode-test.md

@@ -0,0 +1,332 @@
+---
+name: xcode-test
+description: Build and test iOS apps on simulator using XcodeBuildMCP
+argument-hint: "[scheme name or 'current' to use default]"
+---
+
+# Xcode Test Command
+
+<command_purpose>Build, install, and test iOS apps on the simulator using XcodeBuildMCP. Captures screenshots, logs, and verifies app behavior.</command_purpose>
+
+## Introduction
+
+<role>iOS QA Engineer specializing in simulator-based testing</role>
+
+This command tests iOS/macOS apps by:
+- Building for simulator
+- Installing and launching the app
+- Taking screenshots of key screens
+- Capturing console logs for errors
+- Supporting human verification for external flows
+
+## Prerequisites
+
+<requirements>
+- Xcode installed with command-line tools
+- XcodeBuildMCP server connected
+- Valid Xcode project or workspace
+- At least one iOS Simulator available
+</requirements>
+
+## Main Tasks
+
+### 0. Verify XcodeBuildMCP is Installed
+
+<check_mcp_installed>
+
+**First, check if XcodeBuildMCP tools are available.**
+
+Try calling:
+```
+mcp__xcodebuildmcp__list_simulators({})
+```
+
+**If the tool is not found or errors:**
+
+Tell the user:
+```markdown
+**XcodeBuildMCP not installed**
+
+Please install the XcodeBuildMCP server first:
+
+\`\`\`bash
+Install the XcodeBuildMCP server:
+`npx xcodebuildmcp@latest`
+\`\`\`
+
+Then restart Antigravity and run `/xcode-test` again.
+```
+
+**Do NOT proceed** until XcodeBuildMCP is confirmed working.
+
+</check_mcp_installed>
+
+### 1. Discover Project and Scheme
+
+<discover_project>
+
+**Find available projects:**
+```
+mcp__xcodebuildmcp__discover_projs({})
+```
+
+**List schemes for the project:**
+```
+mcp__xcodebuildmcp__list_schemes({ project_path: "/path/to/Project.xcodeproj" })
+```
+
+**If argument provided:**
+- Use the specified scheme name
+- Or "current" to use the default/last-used scheme
+
+</discover_project>
+
+### 2. Boot Simulator
+
+<boot_simulator>
+
+**List available simulators:**
+```
+mcp__xcodebuildmcp__list_simulators({})
+```
+
+**Boot preferred simulator (iPhone 15 Pro recommended):**
+```
+mcp__xcodebuildmcp__boot_simulator({ simulator_id: "[uuid]" })
+```
+
+**Wait for simulator to be ready:**
+Check simulator state before proceeding with installation.
+
+</boot_simulator>
+
+### 3. Build the App
+
+<build_app>
+
+**Build for iOS Simulator:**
+```
+mcp__xcodebuildmcp__build_ios_sim_app({
+  project_path: "/path/to/Project.xcodeproj",
+  scheme: "[scheme_name]"
+})
+```
+
+**Handle build failures:**
+- Capture build errors
+- Create P1 todo for each build error
+- Report to user with specific error details
+
+**On success:**
+- Note the built app path for installation
+- Proceed to installation step
+
+</build_app>
+
+### 4. Install and Launch
+
+<install_launch>
+
+**Install app on simulator:**
+```
+mcp__xcodebuildmcp__install_app_on_simulator({
+  app_path: "/path/to/built/App.app",
+  simulator_id: "[uuid]"
+})
+```
+
+**Launch the app:**
+```
+mcp__xcodebuildmcp__launch_app_on_simulator({
+  bundle_id: "[app.bundle.id]",
+  simulator_id: "[uuid]"
+})
+```
+
+**Start capturing logs:**
+```
+mcp__xcodebuildmcp__capture_sim_logs({
+  simulator_id: "[uuid]",
+  bundle_id: "[app.bundle.id]"
+})
+```
+
+</install_launch>
+
+### 5. Test Key Screens
+
+<test_screens>
+
+For each key screen in the app:
+
+**Take screenshot:**
+```
+mcp__xcodebuildmcp__take_screenshot({
+  simulator_id: "[uuid]",
+  filename: "screen-[name].png"
+})
+```
+
+**Review screenshot for:**
+- UI elements rendered correctly
+- No error messages visible
+- Expected content displayed
+- Layout looks correct
+
+**Check logs for errors:**
+```
+mcp__xcodebuildmcp__get_sim_logs({ simulator_id: "[uuid]" })
+```
+
+Look for:
+- Crashes
+- Exceptions
+- Error-level log messages
+- Failed network requests
+
+</test_screens>
+
+### 6. Human Verification (When Required)
+
+<human_verification>
+
+Pause for human input when testing touches:
+
+| Flow Type | What to Ask |
+|-----------|-------------|
+| Sign in with Apple | "Please complete Sign in with Apple on the simulator" |
+| Push notifications | "Send a test push and confirm it appears" |
+| In-app purchases | "Complete a sandbox purchase" |
+| Camera/Photos | "Grant permissions and verify camera works" |
+| Location | "Allow location access and verify map updates" |
+
+Use AskUserQuestion:
+```markdown
+**Human Verification Needed**
+
+This test requires [flow type]. Please:
+1. [Action to take on simulator]
+2. [What to verify]
+
+Did it work correctly?
+1. Yes - continue testing
+2. No - describe the issue
+```
+
+</human_verification>
+
+### 7. Handle Failures
+
+<failure_handling>
+
+When a test fails:
+
+1. **Document the failure:**
+   - Take screenshot of error state
+   - Capture console logs
+   - Note reproduction steps
+
+2. **Ask user how to proceed:**
+   ```markdown
+   **Test Failed: [screen/feature]**
+
+   Issue: [description]
+   Logs: [relevant error messages]
+
+   How to proceed?
+   1. Fix now - I'll help debug and fix
+   2. Create todo - Add to todos/ for later
+   3. Skip - Continue testing other screens
+   ```
+
+3. **If "Fix now":**
+   - Investigate the issue in code
+   - Propose a fix
+   - Rebuild and retest
+
+4. **If "Create todo":**
+   - Create `{id}-pending-p1-xcode-{description}.md`
+   - Continue testing
+
+</failure_handling>
+
+### 8. Test Summary
+
+<test_summary>
+
+After all tests complete, present summary:
+
+```markdown
+## 📱 Xcode Test Results
+
+**Project:** [project name]
+**Scheme:** [scheme name]
+**Simulator:** [simulator name]
+
+### Build: ✅ Success / ❌ Failed
+
+### Screens Tested: [count]
+
+| Screen | Status | Notes |
+|--------|--------|-------|
+| Launch | ✅ Pass | |
+| Home | ✅ Pass | |
+| Settings | ❌ Fail | Crash on tap |
+| Profile | ⏭️ Skip | Requires login |
+
+### Console Errors: [count]
+- [List any errors found]
+
+### Human Verifications: [count]
+- Sign in with Apple: ✅ Confirmed
+- Push notifications: ✅ Confirmed
+
+### Failures: [count]
+- Settings screen - crash on navigation
+
+### Created Todos: [count]
+- `006-pending-p1-xcode-settings-crash.md`
+
+### Result: [PASS / FAIL / PARTIAL]
+```
+
+</test_summary>
+
+### 9. Cleanup
+
+<cleanup>
+
+After testing:
+
+**Stop log capture:**
+```
+mcp__xcodebuildmcp__stop_log_capture({ simulator_id: "[uuid]" })
+```
+
+**Optionally shut down simulator:**
+```
+mcp__xcodebuildmcp__shutdown_simulator({ simulator_id: "[uuid]" })
+```
+
+</cleanup>
+
+## Quick Usage Examples
+
+```bash
+# Test with default scheme
+/xcode-test
+
+# Test specific scheme
+/xcode-test MyApp-Debug
+
+# Test after making changes
+/xcode-test current
+```
+
+## Integration with /review
+
+When reviewing PRs that touch iOS code, the `/review` command can spawn this as a subagent:
+
+```
+Task general-purpose("Run /xcode-test for scheme [name]. Build, install on simulator, test key screens, check for crashes.")
+```

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Marcos del Cristo
+Copyright (c) 2025 Kieran Klaassen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# Antigravity Cortex
+
+The central "brain" and standard library for Antigravity-powered agents. This package distributes shared **Skills**, **Workflows**, and **Rules** that are injected into project workspaces to ensure consistent, high-quality engineering.
+
+## Architecture
+
+This package manages the `.agent/` directory in your project using a **Manifest-based Sync** system.
+
+*   **Skills** (`.agent/skills/`): Capabilities the agent can pull in on demand (e.g., `git-worktree`, `data-migration-expert`).
+*   **Workflows** (`.agent/workflows/`): Step-by-step guides for specific tasks (e.g., `/deploy`, `/plan`).
+*   **Rules** (`.agent/rules/`): Persistent context and formatting rules (e.g., `00-constitution.md`).
+*   **Browser Agent**: Includes `agent-browser` as a native dependency.
+
+## Installation
+
+To add Antigravity Cortex to your project:
+
+```bash
+# 1. Install the package (Dev Dependency recommended)
+npm install -D ag-cortex
+
+# 2. Initialize the brain
+# This copies the assets to your .agent/ directory and creates a tracking manifest.
+npx ag-cortex install
+```
+
+## Usage
+
+### Updating Assets
+When a new version of `ag-cortex` is released, update your local assets safely:
+
+```bash
+# 1. Update the package
+npm install -D ag-cortex@latest
+
+# 2. Sync the assets
+# This will update modified files and prune orphaned files (keeping your custom files safe).
+npx ag-cortex update
+```
+
+### Checking Status
+Verify your installation and dependencies:
+
+```bash
+npx ag-cortex doctor
+```
+
+---
+*Forked from [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin)*.

package/bin/ag-cortex.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { install, update, doctor } = require('../lib/core');
+
+// Use dynamic import for chalk since v5 is ESM-only
+// Or use a wrapper. For simplicity in this script, we'll try standard require.
+// If chalk v5+ is pure ESM, we might need to stick to chalk@4 or use dynamic import.
+// Let's use dynamic import pattern or fix chalk version in package.json to ^4.1.2 if we want CommonJS.
+// However, let's try to be modern. We'll wrap in an async IIFE.
+
+(async () => {
+    const chalk = (await import('chalk')).default;
+
+    console.log(chalk.bold.blue('🔮 Antigravity Cortex CLI'));
+
+    program
+        .name('ag-cortex')
+        .description('Manage Antigravity skills, rules, and workflows')
+        .version('0.1.0');
+
+    program
+        .command('install')
+        .description('Install Cortex assets into the current project')
+        .action(async () => {
+            try {
+                await install();
+            } catch (error) {
+                console.error(chalk.red('Installation failed:'), error.message);
+                process.exit(1);
+            }
+        });
+
+    program
+        .command('update')
+        .description('Update Cortex assets and prune orphaned files')
+        .action(async () => {
+            try {
+                await update();
+            } catch (error) {
+                console.error(chalk.red('Update failed:'), error.message);
+                process.exit(1);
+            }
+        });
+
+    program
+        .command('doctor')
+        .description('Verify installation and dependencies')
+        .action(async () => {
+            await doctor();
+        });
+
+    program.parse();
+})();

package/lib/core.js

@@ -0,0 +1,165 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Paths
+const PKG_ROOT = path.resolve(__dirname, '..');
+const SOURCE_ASSETS_DIR = path.join(PKG_ROOT, '.agent');
+// When installed in a user project, we assume we are running from node_modules, 
+// so the target project root is likely process.cwd()
+const TARGET_ROOT = process.cwd();
+const TARGET_AGENT_DIR = path.join(TARGET_ROOT, '.agent');
+const MANIFEST_FILE = path.join(TARGET_AGENT_DIR, '.ag-cortex-manifest.json');
+
+/**
+ * Get all files in a directory recursively, returning paths relative to the base dir.
+ */
+async function walk(dir, baseDir = dir) {
+    let results = [];
+    try {
+        const list = await fs.readdir(dir);
+        for (const file of list) {
+            const filePath = path.join(dir, file);
+            const stat = await fs.stat(filePath);
+            if (stat && stat.isDirectory()) {
+                results = results.concat(await walk(filePath, baseDir));
+            } else {
+                results.push(path.relative(baseDir, filePath));
+            }
+        }
+    } catch (e) {
+        if (e.code === 'ENOENT') return [];
+        if (e.code === 'EACCES') {
+            console.error(chalk.red(`   ❌ Permission error accessing: ${dir}`));
+        }
+        throw e;
+    }
+    return results;
+}
+
+async function install() {
+    const chalk = (await import('chalk')).default;
+    console.log(chalk.blue(`📦 Installing Cortex assets to ${TARGET_AGENT_DIR}...`));
+
+    // 1. Ensure source exists
+    if (!await fs.pathExists(SOURCE_ASSETS_DIR)) {
+        throw new Error(`Source assets not found at ${SOURCE_ASSETS_DIR}. Are you running from the package?`);
+    }
+
+    // 2. Get list of assets to install
+    const sourceFiles = await walk(SOURCE_ASSETS_DIR);
+
+    // 3. Prepare Manifest
+    const newManifest = {
+        files: sourceFiles,
+        updatedAt: new Date().toISOString(),
+        version: require('../package.json').version
+    };
+
+    // 4. Copy Files
+    for (const file of sourceFiles) {
+        const srcPath = path.join(SOURCE_ASSETS_DIR, file);
+        const destPath = path.join(TARGET_AGENT_DIR, file);
+
+        await fs.ensureDir(path.dirname(destPath));
+        await fs.copy(srcPath, destPath, { overwrite: true });
+    }
+    console.log(chalk.green(`   ✅ Installed ${sourceFiles.length} files.`));
+
+    console.log(chalk.green(`   ✅ Installed ${sourceFiles.length} files.`));
+
+    // 5. Write Manifest
+    await fs.writeJson(MANIFEST_FILE, newManifest, { spaces: 2 });
+    console.log(chalk.blue(`   📄 Manifest written to ${MANIFEST_FILE}`));
+
+    // 6. Setup Agent Browser
+    const os = require('os');
+    console.log(chalk.blue(`🌐 Setting up Agent Browser...`));
+
+    const isLinux = os.platform() === 'linux';
+
+    try {
+        if (isLinux) {
+            console.log(chalk.yellow(`   🐧 Linux detected: Attempting to install system dependencies...`));
+            console.log(chalk.gray(`      (If this fails, you may need to run with sudo)`));
+            execSync('npx agent-browser install --with-deps', { stdio: 'inherit', cwd: TARGET_ROOT });
+        } else {
+            execSync('npx agent-browser install', { stdio: 'inherit', cwd: TARGET_ROOT });
+        }
+        console.log(chalk.green(`   ✅ Agent Browser installed.`));
+    } catch (e) {
+        if (isLinux) {
+            console.warn(chalk.yellow(`   ⚠️  Automatic setup failed. You likely need sudo for system dependencies.`));
+            console.warn(chalk.bold(`       Please run: sudo npx agent-browser install --with-deps`));
+        } else {
+            console.warn(chalk.yellow(`   ⚠️  Agent Browser setup had issues. Try running: npx agent-browser install --with-deps`));
+        }
+    }
+}
+
+async function update() {
+    const chalk = (await import('chalk')).default;
+    console.log(chalk.blue(`🔄 Updating Cortex assets...`));
+
+    // 1. Load Old Manifest
+    let oldManifest = { files: [] };
+    if (await fs.pathExists(MANIFEST_FILE)) {
+        try {
+            oldManifest = await fs.readJson(MANIFEST_FILE);
+            console.log(chalk.gray(`   Found existing manifest (${oldManifest.files.length} tracked files)`));
+        } catch (e) {
+            console.warn(chalk.yellow(`   Warning: Could not read manifest. Assuming clean slate.`));
+        }
+    } else {
+        console.log(chalk.yellow(`   No manifest found. Treating as clean install (no pruning).`));
+    }
+
+    // 2. Get New Assets List
+    if (!await fs.pathExists(SOURCE_ASSETS_DIR)) throw new Error('Source assets missing.');
+    const newFiles = await walk(SOURCE_ASSETS_DIR);
+    const newFilesSet = new Set(newFiles);
+
+    // 3. Prune Orphans
+    // Orphan = File in oldManifest BUT NOT in newFiles
+    let prunedCount = 0;
+    for (const oldFile of oldManifest.files) {
+        if (!newFilesSet.has(oldFile)) {
+            // SECURITY: Prevent path traversal
+            if (oldFile.includes('..') || path.isAbsolute(oldFile)) {
+                console.warn(chalk.red(`   ⚠️ Security Warning: Skipping pruning of unsafe path: ${oldFile}`));
+                continue;
+            }
+
+            const orphanPath = path.join(TARGET_AGENT_DIR, oldFile);
+            if (await fs.pathExists(orphanPath)) {
+                await fs.remove(orphanPath);
+                console.log(chalk.red(`   🗑️  Pruned: ${oldFile}`));
+                prunedCount++;
+            }
+        }
+    }
+    if (prunedCount > 0) console.log(chalk.green(`   ✅ Pruned ${prunedCount} orphaned files.`));
+
+    // 4. Install/Update (Overwrite)
+    // Run install to handle the copy and manifest update
+    await install();
+}
+
+async function doctor() {
+    const chalk = (await import('chalk')).default;
+    console.log(chalk.bold('🩺 Cortex Doctor'));
+
+    // Check agent-browser
+    try {
+        const packageJson = require('../package.json');
+        const browserVersion = packageJson.dependencies['agent-browser'] || 'unknown';
+        console.log(`   ✅ agent-browser dependency: ${browserVersion}`);
+    } catch (e) {
+        console.log(chalk.red(`   ❌ agent-browser check failed: ${e.message}`));
+    }
+
+    console.log(`   ✅ Environment: Node ${process.version}`);
+    console.log(`   ✅ Package Source: ${PKG_ROOT}`);
+}
+
+module.exports = { install, update, doctor };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "ag-cortex",
+  "version": "0.1.0",
+  "description": "Antigravity Cortex - Agentic Workflow Distribution. The central brain and standard library for Antigravity-powered agents.",
+  "bin": {
+    "ag-cortex": "./bin/ag-cortex.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    ".agent"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "antigravity",
+    "cortex",
+    "agent",
+    "workflows",
+    "skills"
+  ],
+  "author": "Marcos del Cristo",
+  "license": "MIT",
+  "dependencies": {
+    "agent-browser": "^0.8.4",
+    "chalk": "^5.0.0",
+    "commander": "^11.0.0",
+    "fs-extra": "^11.0.0"
+  }
+}