@jaguilar87/gaia-ops 4.7.2 → 5.0.0-beta.3

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "gaia-security",
       "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
-      "version": "4.7.2",
+      "version": "5.0.0-beta.3",
       "source": "./dist/gaia-security"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-ops",
-  "version": "4.7.2",
+  "version": "5.0.0-beta.3",
   "description": "Security-first orchestrator with specialized agents, hooks, and governance for AI coding",
   "author": {
     "name": "jaguilar87"

package/ARCHITECTURE.md

@@ -15,7 +15,7 @@ The package is published as `@jaguilar87/gaia-ops` on npm and installed into a p
 | **Hook** | Python scripts that intercept tool calls before and after execution |
 | **Tool** | Python modules in `tools/` providing context assembly, memory, and validation |
 | **Config** | JSON files in `config/` defining contracts, rules, surface routing, and security |
-| **Orchestrator** | Identity injected by UserPromptSubmit hook; routes requests to the correct agent via on-demand skills |
+| **Orchestrator** | Agent definition in `agents/gaia-orchestrator.md`, activated via `settings.json: { "agent": "gaia-orchestrator" }`; routes requests to the correct agent via on-demand skills |
 
 ## Runtime Flow
 
@@ -23,9 +23,9 @@ The package is published as `@jaguilar87/gaia-ops` on npm and installed into a p
 User request
     |
     v
-user_prompt_submit.py  (UserPromptSubmit hook)
-    |  Inject orchestrator identity via ops_identity.py
-    |  Inject surface routing recommendation (deterministic)
+Orchestrator (agents/gaia-orchestrator.md, activated via settings.json agent config)
+    |  Identity defined in agent definition file
+    |  Surface routing recommendation injected by UserPromptSubmit hook (deterministic)
     |  Skills loaded on-demand: agent-response
     v
 Orchestrator dispatches to agent
@@ -120,9 +120,10 @@ Classifies user tasks into surfaces using signal matching against `config/surfac
 | `live_runtime` | cloud-troubleshooter | pods, services, logs, kubectl, gcloud |
 | `gitops_desired_state` | gitops-operator | manifests, Flux, Helm, Kustomize |
 | `terraform_iac` | terraform-architect | Terraform, Terragrunt, IAM, modules |
-| `app_ci_tooling` | devops-developer | CI/CD, Docker, package tooling |
+| `app_ci_tooling` | developer | CI/CD, Docker, package tooling |
 | `planning_specs` | speckit-planner | specs, plans, task breakdowns |
 | `gaia_system` | gaia | hooks, skills, agents/, CLAUDE.md |
+| `workspace` | gaia-operator | memory, email, schedules, file transfers |
 
 **Classification algorithm:**
 1. Normalize task text
@@ -264,7 +265,7 @@ The adapter layer connects Claude Code's hook protocol to gaia-ops business logi
 | **File (plugin channel)** | `hooks/hooks.json` -- paths use `${CLAUDE_PLUGIN_ROOT}/hooks/` prefix |
 | **File (npm channel)** | `hooks/hooks.json` (symlinked into `.claude/hooks/`) |
 | **What it does** | Maps Claude Code hook events to handler scripts. Defines which events fire which entry points, the tool matchers (Bash, Task, Agent, `*`), and permissions (allow/deny lists). |
-| **Events configured** | PreToolUse (Bash, Task, Agent, SendMessage), PostToolUse, SubagentStop, SessionStart, Stop, TaskCompleted, SubagentStart, UserPromptSubmit (identity injection) |
+| **Events configured** | PreToolUse (Bash, Task, Agent, SendMessage), PostToolUse, SubagentStop, SessionStart, Stop, TaskCompleted, SubagentStart, UserPromptSubmit (routing injection) |
 
 ### HookAdapter ABC Contract
 
@@ -311,7 +312,7 @@ To support a CLI other than Claude Code (e.g., a hypothetical Cursor or Windsurf
 
 | File | Purpose |
 |------|---------|
-| `hooks/modules/identity/ops_identity.py` | Orchestrator identity (injected by UserPromptSubmit) |
+| `agents/gaia-orchestrator.md` | Orchestrator identity and routing (activated via settings.json agent config) |
 | `config/surface-routing.json` | Surface routing config (agent table, signals, dispatch) |
 | `skills/agent-response/SKILL.md` | Contract status handling protocol (on-demand) |
 | `hooks/pre_tool_use.py` | PreToolUse hook entry point |

package/INSTALL.md

@@ -276,7 +276,7 @@ When you update `@jaguilar87/gaia-ops`, these files are **regenerated from templ
 | `.claude/logs/` | ✅ **Preserved** | Safe |
 | Other `.claude/` files | ✅ **Auto-updated via symlinks** | Safe |
 
-Orchestrator identity is injected dynamically by the UserPromptSubmit hook -- no `CLAUDE.md` is generated.
+Orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { "agent": "gaia-orchestrator" }` -- no `CLAUDE.md` is generated.
 
 ### Update Process
 
@@ -431,7 +431,7 @@ A: `npm update @jaguilar87/gaia-ops` - symlinks point to the new version automat
 
 ---
 
-**Version:** 4.4.0-rc.5
-**Last updated:** 2026-03-19
+**Version:** 4.7.2
+**Last updated:** 2026-04-09
 **Maintained by:** Jorge Aguilar + Gaia (meta-agent)
 

package/README.md

@@ -15,9 +15,9 @@ Multi-agent DevOps system that classifies every operation by risk, routes work t
 ### Features
 
 - **Multi-cloud support** - GCP, AWS, Azure
-- **6 agents** - terraform-architect, gitops-operator, cloud-troubleshooter, devops-developer, speckit-planner, gaia-system (meta-agent)
+- **8 agents** - terraform-architect, gitops-operator, cloud-troubleshooter, developer, speckit-planner, gaia-operator, gaia-orchestrator, gaia-system (meta-agent)
 - **Contracts as SSOT** - Cloud-agnostic base contracts with per-cloud extensions (GCP, AWS)
-- **Dynamic identity** - Orchestrator identity injected by UserPromptSubmit hook; skills loaded on-demand
+- **Dynamic identity** - Orchestrator identity defined in `agents/gaia-orchestrator.md`, activated via `settings.json` agent config; skills loaded on-demand
 - **Dual-barrier security** - Settings deny rules (Claude Code native) + hook-level blocking (inalterable via symlink)
 - **Indirect execution detection** - Catches `bash -c`, `eval`, `python -c` wrappers that bypass regex patterns
 - **Approval gates** for T3 operations via native `ask` dialog
@@ -64,7 +64,7 @@ This will:
 4. Create `settings.json` with hooks only (no permissions in settings.json)
 5. Merge deny rules + allow permissions into `settings.local.json` (preserves existing user config)
 
-No `CLAUDE.md` is generated -- orchestrator identity is injected dynamically by the UserPromptSubmit hook.
+No `CLAUDE.md` is generated -- orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { "agent": "gaia-orchestrator" }`.
 
 ### Settings Architecture
 
@@ -105,7 +105,7 @@ Once installed, the agent system is ready:
 claude
 ```
 
-The orchestrator identity is injected dynamically by the UserPromptSubmit hook. Skills are loaded on-demand.
+The orchestrator identity is defined in `agents/gaia-orchestrator.md` and activated via `settings.json` agent config. Skills are loaded on-demand.
 
 Skills and injection diagnosis:
 
@@ -136,7 +136,7 @@ For organization-wide enforcement, deploy `templates/managed-settings.template.j
 
 ```
 node_modules/@jaguilar87/gaia-ops/
-├── agents/              # Agent definitions (6 agents)
+├── agents/              # Agent definitions (8 agents)
 ├── skills/              # Skill modules (21 skills)
 ├── tools/               # Orchestration tools
 ├── hooks/               # Claude Code hooks (modular architecture)

package/agents/cloud-troubleshooter.md

@@ -57,7 +57,7 @@ If unclear, ask before proceeding.
 |------|-------|
 | Fix infrastructure drift | `terraform-architect` |
 | Fix Kubernetes manifests | `gitops-operator` |
-| Application code changes | `devops-developer` |
+| Application code changes | `developer` |
 | gaia-ops modifications | `gaia` |
 
 **This agent never modifies files, never executes writes, never invokes other agents directly.**

package/agents/{devops-developer.md → developer.md}

@@ -1,6 +1,6 @@
 ---
-name: devops-developer
-description: Full-stack DevOps specialist unifying application code, infrastructure, and developer tooling across Node.js/TypeScript and Python ecosystems.
+name: developer
+description: Full-stack software engineer for application code, CI/CD, and developer tooling across Node.js/TypeScript and Python stacks.
 tools: Read, Edit, Write, Agent, Glob, Grep, Bash, Task, Skill, WebSearch, WebFetch
 model: inherit
 maxTurns: 50
@@ -46,6 +46,13 @@ You are a full-stack software engineer. You build, debug, and improve applicatio
 | Live cloud diagnostics | `cloud-troubleshooter` |
 | gaia-ops modifications | `gaia` |
 
+During investigation, if you discover that a resource type is managed
+by Terraform, Terragrunt, Helm, Flux, or any other IaC/GitOps tool,
+creating new instances of that resource belongs to the agent that owns
+that tool — even if you need the resource as a prerequisite for your
+task. Report it as a dependency or blocker. The fastest path for you
+is the wrong path for the project if it causes drift.
+
 ## Domain Errors
 
 | Error | Action |

package/agents/gaia-operator.md

@@ -0,0 +1,60 @@
+---
+name: gaia-operator
+description: Workspace operator — extensible agent for personal workspace tasks, memory management, and integrations
+tools: Read, Edit, Write, Glob, Grep, Bash, Task, Skill, WebSearch, WebFetch
+model: sonnet
+skills:
+  - agent-protocol
+  - security-tiers
+  - command-execution
+  - context-updater
+  - memory-management
+  - gmail-triage
+  - gws-setup
+---
+
+# Workspace Operator
+
+## Identity
+
+You are the workspace operator — an extensible agent that specializes in personal workspace
+tasks. You manage the user's persistent memory, workspace organization, and tool integrations.
+Your capabilities grow through on-demand skills — each new integration is a skill, not a
+code change.
+
+## Core Capabilities
+
+- **Memory management** — MEMORY.md index, memory files, cross-session knowledge persistence
+- **Web research** — search and summarize information for the user
+- **Workspace file operations** — organize, transfer, manage files across the workspace
+
+Future capabilities arrive as on-demand skills (email, calendar, scheduling, etc.).
+Load them with `Skill('skill-name')` when the task requires it.
+
+## Scope
+
+### CAN DO
+
+| Task | How |
+|------|-----|
+| Create/update/search memory files | Read/Write + memory-management skill |
+| Web research and summarization | WebSearch + WebFetch |
+| File organization and management | Bash + Read/Write |
+| Load integration skills on-demand | Skill('gmail-policy'), Skill('calendar'), etc. |
+
+### CANNOT DO → DELEGATE
+
+| Task | Agent |
+|------|-------|
+| Application code, CI/CD, Docker | developer |
+| Terraform, cloud resources, IaC | terraform-architect |
+| Kubernetes manifests, Helm, Flux | gitops-operator |
+| Live infrastructure diagnostics | cloud-troubleshooter |
+| Gaia system changes (hooks, skills, agents) | gaia-system |
+| Feature planning and specs | speckit-planner |
+
+## Domain Errors
+
+- **Memory index conflict** — MEMORY.md does not match actual files → reconcile index before proceeding
+- **Skill not found** — requested integration skill does not exist → report to orchestrator, suggest creation via gaia-system
+- **File permission denied** — cannot access target path → verify path and permissions, report exact error

package/agents/gaia-orchestrator.md

@@ -0,0 +1,113 @@
+---
+name: gaia-orchestrator
+description: Gaia governance orchestrator — routes requests to specialist agents, enforces security tiers, presents results
+tools: Agent, SendMessage, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, TaskGet, CronCreate, CronDelete, CronList, WebSearch, WebFetch, ToolSearch
+disallowedTools: [Read, Glob, Grep, Bash, Edit, Write, NotebookEdit, EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree]
+model: inherit
+maxTurns: 200
+skills:
+---
+
+# Gaia Orchestrator
+
+The user installed Gaia, a governance layer for Claude Code agents.
+Your role: analyze requests, decompose them into specialist tasks,
+dispatch agents with focused objectives, and consolidate their results.
+
+## Why delegation matters
+
+- Agents are injected with domain skills and security policies at spawn time
+- Each agent has its own context window optimized for its domain
+- Agents return structured json:contract responses (atomic, preserves your context)
+- Direct tool use bypasses the governance pipeline (no audit trail, no security tiers)
+- Built-in subagent types (Explore, Plan) return raw text that inflates your context
+
+## Capabilities
+
+- Route user requests to specialist agents using deterministic signal matching
+- Enforce security tiers and approval workflows for T3 operations
+- Present structured agent responses and manage approval cycles
+- Track work progress across multi-agent tasks
+
+## Your tools (ONLY these exist)
+
+- **Agent** -- dispatch specialist agents (each has injected skills and tool restrictions)
+- **SendMessage** -- resume a running agent by name or ID
+- **AskUserQuestion** -- clarify with user, or present approval requests
+- **Skill** -- load on-demand procedures (agent-response, orchestrator-approval)
+- **TaskCreate/Update/List/Get** -- track work progress
+- **WebSearch/WebFetch** -- web research (allowed, no delegation needed)
+- **ToolSearch** -- discover deferred tool schemas
+
+You do NOT have: Read, Glob, Grep, Bash, Edit, Write.
+These tools do not exist in your session. Do not attempt to use them.
+
+## Routing
+
+Each message may include a routing suggestion from signal matching.
+Use it as input, not as a directive. Match the user's request against
+these surface intents. Dispatch ALL agents whose intent matches.
+If 2+ match, dispatch in parallel.
+
+| Surface | Agent | Intent |
+|---------|-------|--------|
+| live_runtime | cloud-troubleshooter | Inspect, diagnose, or validate actual state of running systems — pods, logs, cloud resources, SSH, network |
+| terraform_iac | terraform-architect | Create, modify, review, or validate IaC — Terraform, Terragrunt, cloud resources, state, plan/apply |
+| gitops_desired_state | gitops-operator | Create, modify, or review Kubernetes desired state — Flux, Helm, Kustomize, manifests |
+| app_ci_tooling | developer | Write, modify, test, or build app code — Node/TS, Python, Docker, CI/CD, packages |
+| planning_specs | speckit-planner | Plan features, break down requirements, create specs, plans, task lists |
+| gaia_system | gaia-system | Modify or analyze Gaia itself — hooks, skills, agents, routing, security, architecture |
+| workspace | gaia-operator | Personal workspace — memory, schedules, loops, email, file transfers, general automation |
+
+If no intent matches clearly — ask the user to clarify.
+Do not default to built-in agents (Explore, Plan) for tasks that match a surface intent.
+
+## Dispatch strategy
+
+When dispatching, ask yourself:
+1. What domains does this request touch? (match against intents above)
+2. What specific question does each specialist need to answer?
+3. Can they work in parallel, or does one depend on another?
+
+Each agent gets a DIFFERENT prompt focused on their domain.
+Do not send the same user message to multiple agents — decompose it.
+
+## Briefing agents
+
+Dispatch objectives, not commands. Agents have domain skills,
+injected project-context, and investigation procedures.
+They choose their own execution path.
+
+Your prompt = the objective + business requirements.
+Never include:
+- File names, paths, or directory structures to create
+- Resource names, values, or configuration details
+- Shell commands or implementation steps
+- "What to create" or "How to implement" sections
+
+Agents receive project-context with paths, names, and topology.
+They investigate existing patterns before proposing anything.
+Trust the agent's domain expertise — your job is WHAT to achieve
+and WHY, never HOW.
+
+## Response handling
+
+When an agent returns a json:contract, load Skill('agent-response').
+When an agent returns REVIEW with approval_id, load Skill('orchestrator-approval').
+
+## Memory Protocol
+
+Claude Code handles auto-save and auto-prune natively.
+Gaia complements with structured curation via gaia-operator:
+
+- After productive sessions with decisions → dispatch gaia-operator
+- Operator loads memory-management skill → curates, categorizes, deduplicates
+- Does NOT replace Claude Code's native memory — organizes it
+
+Memory tasks route to workspace surface → gaia-operator.
+
+## Failures
+
+- Hook blocks a command -- relay the message verbatim, do not suggest alternatives
+- Routing unclear -- ask the user
+- Agents contradict -- present both sides, user decides

package/agents/gaia-system.md

@@ -11,6 +11,7 @@ skills:
   - investigation
   - command-execution
   - gaia-patterns
+  - gaia-release
   - skill-creation
 ---
 
@@ -47,7 +48,7 @@ You are the **meta-agent** — the agent that understands agents. Your specialty
 | Terraform / cloud infrastructure | `terraform-architect` |
 | Kubernetes / GitOps | `gitops-operator` |
 | Live cloud diagnostics | `cloud-troubleshooter` |
-| Application code | `devops-developer` |
+| Application code | `developer` |
 
 ## Domain Errors
 

package/agents/gitops-operator.md

@@ -46,7 +46,7 @@ You are a senior GitOps operator. You manage the entire lifecycle of Kubernetes
 |------|-------|
 | Terraform / cloud infrastructure | `terraform-architect` |
 | Query live cloud state (`gcloud`, `aws`) | `cloud-troubleshooter` |
-| Application code (Python, Node.js) | `devops-developer` |
+| Application code (Python, Node.js) | `developer` |
 | gaia-ops modifications | `gaia` |
 
 ## Domain Errors

package/agents/speckit-planner.md

@@ -58,7 +58,7 @@ If `speckit_root` resolves to a directory that does not exist, create it (T3 --
 | Execute tasks from tasks.md | Orchestrator (routes to agents) |
 | Execute infrastructure changes | `terraform-architect` |
 | Execute Kubernetes operations | `gitops-operator` |
-| Run application builds or tests | `devops-developer` |
+| Run application builds or tests | `developer` |
 | Diagnose cloud issues | `cloud-troubleshooter` |
 
 ## Domain Errors

package/agents/terraform-architect.md

@@ -17,10 +17,12 @@ skills:
 
 ## Workflow
 
-1. **Triage first**: When checking infrastructure state, run the fast-queries Terraform or cloud triage script before running plan/apply.
-2. **Deep analysis**: When investigating drift or complex module dependencies, follow the investigation phases.
-3. **Before T3 operations**: When `terragrunt apply` is needed, present a REVIEW plan first. If a hook blocks it, include the `approval_id` from the deny response in your REVIEW approval_request.
-4. **Update context**: Before completing, if you discovered infrastructure topology, service accounts, or network configs not in Project Context, emit a CONTEXT_UPDATE block.
+1. **Understand what exists**: Follow the investigation phases — read existing modules, discover naming patterns, find the project's Terraform organization before proposing anything.
+2. **Check current state**: When drift is suspected or runtime data is needed, run the fast-queries Terraform or cloud triage script.
+3. **Propose with evidence**: Build a plan grounded in what you found — which existing module you followed, which patterns you matched, what the plan output shows.
+4. **Present for review**: When `terragrunt apply` or other T3 operations are needed, present a REVIEW plan first. If a hook blocks it, include the `approval_id` from the deny response in your REVIEW approval_request.
+5. **Execute and verify**: After approval (T3) or after investigation confirms patterns (T0-T2), create/modify files and run verification.
+6. **Update context**: Before completing, if you discovered infrastructure topology, service accounts, or network configs not in Project Context, emit a CONTEXT_UPDATE block.
 
 ## Identity
 
@@ -46,7 +48,7 @@ You are a senior Terraform architect. You manage the entire lifecycle of cloud i
 |------|-------|
 | Query live cloud state (`gcloud`, `aws`) | `cloud-troubleshooter` |
 | Kubernetes / Flux manifests | `gitops-operator` |
-| Application code (Python, Node.js) | `devops-developer` |
+| Application code (Python, Node.js) | `developer` |
 | gaia-ops modifications | `gaia` |
 
 ## Domain Errors

package/bin/README.md

@@ -146,4 +146,4 @@ npx gaia-scan --non-interactive
 
 ---
 
-**Version:** 4.5.0 | **Updated:** 2026-03-24 | **Scripts:** 11
+**Version:** 4.7.2 | **Updated:** 2026-04-09 | **Scripts:** 11

package/bin/gaia-doctor.js

@@ -93,17 +93,27 @@ async function checkSettingsJson() {
     const data = JSON.parse(await fs.readFile(path, 'utf-8'));
     const issues = [];
 
-    // Check hooks are configured
-    if (!data.hooks) {
-      issues.push('No hooks configured');
+    // Check hooks are configured — hooks may live in settings.json OR
+    // settings.local.json (gaia-update/gaia-scan puts them in local).
+    let hooksConfig = data.hooks || null;
+    const localPath = join(CWD, '.claude', 'settings.local.json');
+    if (!hooksConfig && existsSync(localPath)) {
+      try {
+        const localData = JSON.parse(await fs.readFile(localPath, 'utf-8'));
+        if (localData.hooks) hooksConfig = localData.hooks;
+      } catch { /* ignore parse errors */ }
+    }
+
+    if (!hooksConfig) {
+      issues.push('No hooks configured (check settings.json and settings.local.json)');
     } else {
-      const hookTypes = Object.keys(data.hooks);
+      const hookTypes = Object.keys(hooksConfig);
       if (!hookTypes.includes('PreToolUse')) issues.push('Missing PreToolUse hook');
       if (!hookTypes.includes('PostToolUse')) issues.push('Missing PostToolUse hook');
     }
 
     // Check permissions — now live in settings.local.json (not settings.json)
-    const localPath = join(CWD, '.claude', 'settings.local.json');
+    // localPath already declared above for hooks check
     let permCount = 0;
     if (existsSync(localPath)) {
       try {
@@ -125,7 +135,7 @@ async function checkSettingsJson() {
       return { name: 'settings.json', ok: false, detail: issues.join('; '), fix: 'Run gaia-scan or npx gaia-update' };
     }
 
-    const hookCount = data.hooks ? Object.keys(data.hooks).length : 0;
+    const hookCount = hooksConfig ? Object.keys(hooksConfig).length : 0;
     return { name: 'settings.json', ok: true, detail: `${hookCount} hook types, ${permCount} rules` };
   } catch {
     return { name: 'settings.json', ok: false, detail: 'Invalid JSON', fix: 'Delete and run gaia-scan' };
@@ -331,12 +341,18 @@ async function autoFix() {
     if (existsSync(packagePath)) {
       const relPath = relative(claudeDir, packagePath);
       const names = ['agents', 'tools', 'hooks', 'commands', 'templates', 'config', 'speckit', 'skills'];
+      // Use junctions on Windows (no admin required), regular symlinks elsewhere
+      const linkType = process.platform === 'win32' ? 'junction' : 'dir';
 
       for (const name of names) {
         const link = join(claudeDir, name);
         if (!existsSync(link)) {
           try {
-            await fs.symlink(join(relPath, name), link);
+            // Junctions on Windows require absolute targets; symlinks on Unix use relative
+            const target = process.platform === 'win32'
+              ? join(packagePath, name)
+              : join(relPath, name);
+            await fs.symlink(target, link, linkType);
             console.log(chalk.green(`    Fixed: .claude/${name} symlink`));
             fixed++;
           } catch {

package/bin/gaia-scan

@@ -1,14 +1,38 @@
-#!/usr/bin/env bash
-# Shell wrapper for gaia-scan CLI.
-# Invokes the Python scanner with all forwarded arguments.
-# Used as the npm bin entry point for `npx gaia-scan` / `npx gaia scan`.
+#!/usr/bin/env node
 
-set -euo pipefail
+/**
+ * Cross-platform wrapper for gaia-scan CLI.
+ * Invokes the Python scanner with all forwarded arguments.
+ * Used as the npm bin entry point for `npx gaia-scan`.
+ *
+ * Replaces the previous bash wrapper so that it works on Windows
+ * (where /usr/bin/env bash does not exist).
+ */
 
-SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || realpath "$0" 2>/dev/null || echo "$0")")" && pwd)"
-PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
 
-# Ensure PYTHONPATH includes the plugin root so `tools.scan` resolves
-export PYTHONPATH="${PLUGIN_ROOT}${PYTHONPATH:+:${PYTHONPATH}}"
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pluginRoot = join(__dirname, '..');
+const scanScript = join(__dirname, 'gaia-scan.py');
 
-exec python3 "${SCRIPT_DIR}/gaia-scan.py" "$@"
+// Forward all CLI arguments after the script name
+const args = process.argv.slice(2);
+
+// Set PYTHONPATH so `tools.scan` resolves inside the package
+const sep = process.platform === 'win32' ? ';' : ':';
+const pythonPath = process.env.PYTHONPATH
+  ? `${pluginRoot}${sep}${process.env.PYTHONPATH}`
+  : pluginRoot;
+
+try {
+  execFileSync('python3', [scanScript, ...args], {
+    stdio: 'inherit',
+    env: { ...process.env, PYTHONPATH: pythonPath },
+  });
+} catch (error) {
+  // execFileSync throws on non-zero exit; propagate the exit code
+  process.exit(error.status || 1);
+}

package/bin/gaia-skills-diagnose.js

@@ -28,12 +28,13 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 
-const META_AGENTS = new Set(["gaia-system", "Explore", "Plan"]);
+const META_AGENTS = new Set(["gaia-system", "gaia-orchestrator", "Explore", "Plan", "general-purpose", "claude-code-guide"]);
 const CONTEXT_INJECTED_AGENTS = new Set([
+  "gaia-operator",
   "terraform-architect",
   "gitops-operator",
   "cloud-troubleshooter",
-  "devops-developer",
+  "developer",
 ]);
 const REQUIRED_PROJECT_SKILLS = ["agent-protocol", "context-updater"];
 
@@ -180,7 +181,9 @@ function resolveRuntimePaths(projectRoot) {
     hooksDir: inProject && exists(path.join(claudeDir, "hooks"))
       ? path.join(claudeDir, "hooks")
       : path.join(PACKAGE_ROOT, "hooks"),
-    settingsPath: path.join(claudeDir, "settings.json"),
+    settingsPath: exists(path.join(claudeDir, "settings.json"))
+      ? path.join(claudeDir, "settings.json")
+      : path.join(claudeDir, "settings.local.json"),
     testsDir: path.join(PACKAGE_ROOT, "tests"),
   };
 
@@ -477,12 +480,12 @@ function validateInjectionWiring(ctx, findings, checks) {
   } else {
     const content = readText(preToolUsePath);
 
-    if (!content.includes("def _inject_project_context")) {
+    if (!content.includes("build_project_context")) {
       addFinding(findings, {
         severity: "high",
         code: "CONTEXT_INJECTION_FUNCTION_MISSING",
         title: "Context injection function missing",
-        detail: "_inject_project_context() not found in pre_tool_use.py.",
+        detail: "build_project_context() not found in pre_tool_use.py.",
         evidence: preToolUsePath,
         remediation: "Reintroduce or repair context injection handler.",
       });
@@ -607,7 +610,12 @@ function validateRoutingContract(ctx, findings, checks) {
   }
 
   const content = readText(validatorPath);
-  const match = content.match(/AVAILABLE_AGENTS\s*=\s*\[(.*?)\]/s);
+  // Try AVAILABLE_AGENTS first, then fall back to _BASE_AGENTS (used when
+  // AVAILABLE_AGENTS is derived via list comprehension)
+  let match = content.match(/AVAILABLE_AGENTS\s*=\s*\[(.*?)\]/s);
+  if (!match) {
+    match = content.match(/_BASE_AGENTS\s*=\s*\[(.*?)\]/s);
+  }
   if (!match) {
     addFinding(findings, {
       severity: "medium",
@@ -615,7 +623,7 @@ function validateRoutingContract(ctx, findings, checks) {
       title: "Could not parse AVAILABLE_AGENTS",
       detail: "Routing contract check skipped.",
       evidence: validatorPath,
-      remediation: "Keep AVAILABLE_AGENTS as a simple static list for validation tooling.",
+      remediation: "Keep AVAILABLE_AGENTS or _BASE_AGENTS as a simple static list for validation tooling.",
     });
     checks.push({ name: "routing-contract", ok: false, detail: "could not parse AVAILABLE_AGENTS" });
     return;
@@ -626,7 +634,7 @@ function validateRoutingContract(ctx, findings, checks) {
   );
 
   const missingOnDisk = [...availableAgents].filter((agent) => !META_AGENTS.has(agent) && !agentsOnDisk.has(agent));
-  const missingInValidator = [...agentsOnDisk].filter((agent) => !availableAgents.has(agent));
+  const missingInValidator = [...agentsOnDisk].filter((agent) => !META_AGENTS.has(agent) && !availableAgents.has(agent));
 
   if (missingOnDisk.length > 0) {
     addFinding(findings, {
@@ -690,8 +698,8 @@ function detectLegacyGapPatterns(ctx, findings, checks) {
   const conftestPath = path.join(testsDir, "conftest.py");
   if (exists(conftestPath)) {
     const content = readText(conftestPath);
-    // CLAUDE.md is no longer generated -- identity injected by UserPromptSubmit hook.
-    // conftest.py fixture now falls back to ops_identity.py + dispatch/response skills.
+    // CLAUDE.md is no longer generated -- identity lives in agents/gaia-orchestrator.md.
+    // conftest.py fixture reads agents/gaia-orchestrator.md directly.
   }
 
   checks.push({
@@ -756,7 +764,7 @@ function runTestProbe(ctx, findings, checks) {
       });
     }
 
-    // CLAUDE.md is no longer required -- conftest.py falls back to ops_identity.py
+    // CLAUDE.md is no longer required -- conftest.py reads agents/gaia-orchestrator.md
   }
 
   checks.push({