@codexa/cli 9.0.12 → 9.0.13

package/commands/plan.ts

@@ -2,6 +2,7 @@ import { getDb } from "../db/connection";
 import { initSchema, getArchitecturalAnalysisForSpec } from "../db/schema";
 import { resolveSpec } from "./spec-resolver";
 import { CodexaError, ValidationError } from "../errors";
+import { resolveAgent, resolveAgentName, suggestAgent, getCanonicalAgentNames } from "../context/agent-registry";
 
 export function generateSpecId(name: string): string {
     const date = new Date().toISOString().split("T")[0];
@@ -87,10 +88,11 @@ export function planStart(description: string, options: { fromAnalysis?: string;
                 const files = step.files && step.files.length > 0 ? JSON.stringify(step.files) : null;
                 const dependsOn = step.dependsOn && step.dependsOn.length > 0 ? JSON.stringify(step.dependsOn) : null;
 
+                const normalizedStepAgent = step.agent ? resolveAgentName(step.agent) : null;
                 db.run(
                     `INSERT INTO tasks (spec_id, number, name, agent, depends_on, can_parallel, files)
                      VALUES (?, ?, ?, ?, ?, ?, ?)`,
-                    [specId, step.number, step.name, step.agent || null, dependsOn, 1, files]
+                    [specId, step.number, step.name, normalizedStepAgent, dependsOn, 1, files]
                 );
                 tasksCreated++;
             }
@@ -266,6 +268,22 @@ export function planTaskAdd(options: {
         }
     }
 
+    // Validar e normalizar agent name (R3)
+    let normalizedAgent: string | null = options.agent || null;
+    if (normalizedAgent) {
+        const entry = resolveAgent(normalizedAgent);
+        if (!entry) {
+            const suggestion = suggestAgent(normalizedAgent);
+            const hint = suggestion
+                ? `\nVoce quis dizer: "${suggestion}"?`
+                : `\nAgentes validos: ${getCanonicalAgentNames().join(", ")}`;
+            throw new ValidationError(
+                `Agente desconhecido: "${normalizedAgent}".${hint}`
+            );
+        }
+        normalizedAgent = entry.canonical;
+    }
+
     // Parsear arquivos
     let files: string[] = [];
     if (options.files) {
@@ -279,7 +297,7 @@ export function planTaskAdd(options: {
             spec.id,
             nextNumber,
             options.name,
-            options.agent || null,
+            normalizedAgent,
             dependsOn.length > 0 ? JSON.stringify(dependsOn) : null,
             options.sequential ? 0 : 1,
             files.length > 0 ? JSON.stringify(files) : null,
@@ -295,7 +313,7 @@ export function planTaskAdd(options: {
     ]);
 
     console.log(`\nTask #${nextNumber} adicionada: ${options.name}`);
-    if (options.agent) console.log(`  Agente: ${options.agent}`);
+    if (normalizedAgent) console.log(`  Agente: ${normalizedAgent}${normalizedAgent !== options.agent ? ` (normalizado de "${options.agent}")` : ""}`);
     if (dependsOn.length > 0) console.log(`  Depende de: ${dependsOn.join(", ")}`);
     if (files.length > 0) console.log(`  Arquivos: ${files.join(", ")}`);
     console.log(`  Paralelizavel: ${options.sequential ? "Nao" : "Sim"}\n`);

package/commands/task.ts

@@ -9,6 +9,8 @@ import { loadTemplate } from "../templates/loader";
 import { TaskStateError, ValidationError, KnowledgeBlockError } from "../errors";
 import { resolveSpec, resolveSpecOrNull } from "./spec-resolver";
 import { getAgentDomain, domainToScope } from "../context/domains";
+import { resolveAgent } from "../context/agent-registry";
+import { loadAgentExpertise, getAgentDescription } from "../context/agent-expertise";
 
 export function taskNext(json: boolean = false, specId?: string): void {
   initSchema();
@@ -224,11 +226,24 @@ export function taskStart(ids: string, json: boolean = false, fullContext: boole
           confidence: p.confidence,
         }));
 
+      // R1: Load condensed expertise from agent .md
+      const agentExpertise = task.agent ? loadAgentExpertise(task.agent) : "";
+
+      // R4: Build agent identity string
+      const agentEntry = task.agent ? resolveAgent(task.agent) : null;
+      const agentIdentity = agentEntry
+        ? `## IDENTIDADE DO AGENTE\n\nVoce e um ${agentEntry.description}.\nSiga os principios e padroes descritos abaixo.\n`
+        : "";
+
+      // R5: Get description for orchestrator use
+      const agentDescription = task.agent ? getAgentDescription(task.agent) : null;
+
       return {
         taskId: task.id,
         number: task.number,
         name: task.name,
         agent: task.agent,
+        agentDescription,
         files: taskFiles,
         // AVISO PARA O ORQUESTRADOR - NAO EXECUTE, DELEGUE
         _orchestratorWarning: "NAO execute esta task diretamente. Use Task tool com subagent_type='general-purpose' para delegar. O campo 'subagentContext' abaixo e o prompt para o SUBAGENT.",
@@ -248,6 +263,10 @@ export function taskStart(ids: string, json: boolean = false, fullContext: boole
         // Contexto para o SUBAGENT (o orquestrador deve passar isso via Task tool)
         subagentContext: loadTemplate("subagent-context", {
           filesList: taskFiles.map(f => `  - ${f}`).join('\n') || '  (nenhum arquivo especificado - analise o contexto)',
+          agentIdentity,
+          agentExpertise: agentExpertise
+            ? `\n## EXPERTISE DO AGENTE\n\n${agentExpertise}\n\n`
+            : '',
         }),
         // Instrucoes de retorno para o SUBAGENT
         subagentReturnProtocol: loadTemplate("subagent-return-protocol", {

package/commands/utils.test.ts

@@ -29,10 +29,14 @@ describe("Domain exports from utils (backward compatibility)", () => {
     expect(domainToScope(domain)).toBe("backend");
   });
 
+  it("aliases now resolve via registry", () => {
+    expect(getAgentDomain("frontend-next")).toBe("frontend");
+    expect(getAgentDomain("database-postgres")).toBe("database");
+  });
+
   it("unknown agents return null domain and 'all' scope", () => {
-    expect(getAgentDomain("frontend-next")).toBeNull();
-    expect(getAgentDomain("database-postgres")).toBeNull();
     expect(getAgentDomain("general-purpose")).toBeNull();
+    expect(getAgentDomain("some-unknown-agent")).toBeNull();
     expect(domainToScope(getAgentDomain("general-purpose"))).toBe("all");
   });
 });

package/commands/utils.ts

@@ -11,6 +11,8 @@ import pkg from "../package.json";
 export { getContextForSubagent, getMinimalContextForSubagent } from "../context/generator";
 export { MAX_CONTEXT_SIZE } from "../context/assembly";
 export { AGENT_DOMAIN, getAgentDomain, domainToScope } from "../context/domains";
+export { resolveAgent, resolveAgentName, suggestAgent, getCanonicalAgentNames } from "../context/agent-registry";
+export { loadAgentExpertise, getAgentDescription } from "../context/agent-expertise";
 
 export function status(json: boolean = false, specId?: string): void {
     initSchema();

package/context/agent-expertise.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { loadAgentExpertise, getAgentDescription, clearExpertiseCache } from "./agent-expertise";
+
+beforeEach(() => {
+  clearExpertiseCache();
+});
+
+// ── loadAgentExpertise ───────────────────────────────────────
+
+describe("loadAgentExpertise", () => {
+  it("returns non-empty string for known agents", () => {
+    const expertise = loadAgentExpertise("golang-pro");
+    expect(expertise.length).toBeGreaterThan(0);
+  });
+
+  it("resolves aliases before loading", () => {
+    const byCanonical = loadAgentExpertise("golang-pro");
+    clearExpertiseCache();
+    const byAlias = loadAgentExpertise("backend-go");
+    expect(byCanonical).toBe(byAlias);
+  });
+
+  it("loads different expertise for different agents", () => {
+    const goExpertise = loadAgentExpertise("golang-pro");
+    clearExpertiseCache();
+    const flutterExpertise = loadAgentExpertise("frontend-flutter");
+    expect(goExpertise).not.toBe(flutterExpertise);
+  });
+
+  it("returns empty for unknown agents", () => {
+    expect(loadAgentExpertise("nonexistent-agent")).toBe("");
+  });
+
+  it("returns empty for empty input", () => {
+    expect(loadAgentExpertise("")).toBe("");
+  });
+
+  it("respects 2.5KB budget", () => {
+    // Check all known agents
+    const agents = ["golang-pro", "expert-csharp-developer", "backend-javascript",
+      "expert-nextjs-developer", "frontend-flutter", "expert-postgres-developer",
+      "testing-unit", "security-specialist"];
+
+    for (const agent of agents) {
+      clearExpertiseCache();
+      const expertise = loadAgentExpertise(agent);
+      // Allow small margin for truncation message
+      expect(expertise.length).toBeLessThanOrEqual(2560 + 100);
+    }
+  });
+
+  it("strips YAML frontmatter", () => {
+    const expertise = loadAgentExpertise("golang-pro");
+    expect(expertise).not.toContain("---\nname:");
+    expect(expertise).not.toContain("invocation:");
+  });
+
+  it("strips redundant Retorno section", () => {
+    const expertise = loadAgentExpertise("golang-pro");
+    expect(expertise).not.toContain("**Retorno**: Siga");
+  });
+
+  it("contains agent-specific content", () => {
+    const goExpertise = loadAgentExpertise("golang-pro");
+    expect(goExpertise).toContain("Go");
+
+    clearExpertiseCache();
+    const flutterExpertise = loadAgentExpertise("frontend-flutter");
+    expect(flutterExpertise).toContain("Flutter");
+  });
+
+  it("caches results across calls", () => {
+    const first = loadAgentExpertise("golang-pro");
+    const second = loadAgentExpertise("golang-pro");
+    expect(first).toBe(second);
+  });
+});
+
+// ── getAgentDescription ──────────────────────────────────────
+
+describe("getAgentDescription", () => {
+  it("returns description for known agent by canonical name", () => {
+    const desc = getAgentDescription("golang-pro");
+    expect(desc).not.toBeNull();
+    expect(desc).toContain("Go");
+  });
+
+  it("returns description for known agent by alias", () => {
+    const desc = getAgentDescription("backend-go");
+    expect(desc).not.toBeNull();
+    expect(desc).toContain("Go");
+  });
+
+  it("returns null for unknown agent", () => {
+    expect(getAgentDescription("nonexistent")).toBeNull();
+  });
+
+  it("returns null for empty input", () => {
+    expect(getAgentDescription("")).toBeNull();
+  });
+});

package/context/agent-expertise.ts

@@ -0,0 +1,134 @@
+// ═══════════════════════════════════════════════════════════════
+// AGENT EXPERTISE LOADER (v9.5)
+// Loads and condenses agent .md expertise for injection into
+// the subagent prompt. Budget: max 2.5KB per agent.
+// ═══════════════════════════════════════════════════════════════
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { resolveAgent } from "./agent-registry";
+
+const MAX_EXPERTISE_SIZE = 2560; // 2.5KB budget
+
+const expertiseCache = new Map<string, string>();
+
+/**
+ * Find the agents directory.
+ * Checks: 1) .claude/agents/ in cwd  2) plugins dir via git root
+ */
+export function findAgentsDir(): string | null {
+  // 1. Check synced agents in project
+  const projectAgents = join(process.cwd(), ".claude", "agents");
+  if (existsSync(projectAgents)) return projectAgents;
+
+  // 2. Dev repo: git root + plugins/codexa-workflow/agents/
+  try {
+    const gitRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf-8" }).trim();
+    const pluginDir = join(gitRoot, "plugins", "codexa-workflow", "agents");
+    if (existsSync(pluginDir)) return pluginDir;
+  } catch {
+    // Not in git repo
+  }
+
+  return null;
+}
+
+/**
+ * Load and condense expertise from an agent .md file.
+ * Strips frontmatter, condenses code blocks, truncates to budget.
+ * Returns empty string if agent not found or has no file.
+ */
+export function loadAgentExpertise(agentName: string): string {
+  if (!agentName) return "";
+
+  const cached = expertiseCache.get(agentName);
+  if (cached !== undefined) return cached;
+
+  const entry = resolveAgent(agentName);
+  if (!entry) {
+    expertiseCache.set(agentName, "");
+    return "";
+  }
+
+  const agentsDir = findAgentsDir();
+  if (!agentsDir) {
+    expertiseCache.set(agentName, "");
+    return "";
+  }
+
+  const filePath = join(agentsDir, `${entry.filename}.md`);
+  if (!existsSync(filePath)) {
+    expertiseCache.set(agentName, "");
+    return "";
+  }
+
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const expertise = extractAndCondense(raw);
+    expertiseCache.set(agentName, expertise);
+    return expertise;
+  } catch {
+    expertiseCache.set(agentName, "");
+    return "";
+  }
+}
+
+/**
+ * Get agent description from registry (R5).
+ */
+export function getAgentDescription(agentName: string): string | null {
+  const entry = resolveAgent(agentName);
+  return entry?.description ?? null;
+}
+
+/**
+ * Clear the expertise cache (for tests).
+ */
+export function clearExpertiseCache(): void {
+  expertiseCache.clear();
+}
+
+// ── Internal helpers ─────────────────────────────────────────
+
+function extractAndCondense(raw: string): string {
+  // Strip YAML frontmatter (--- ... ---)
+  const match = raw.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  if (!match) return "";
+  let body = match[1].trim();
+
+  // Remove redundant "Retorno" footer (already in return protocol template)
+  body = body.replace(/---\s*\n+\*\*Retorno\*\*:.*$/s, "").trim();
+
+  // Condense code blocks: keep ≤8 lines as-is, >8 keeps first 6
+  body = condenseCodeBlocks(body);
+
+  // Truncate to budget at section boundary
+  if (body.length > MAX_EXPERTISE_SIZE) {
+    const truncPoint = findSectionBoundary(body, MAX_EXPERTISE_SIZE - 80);
+    body = body.substring(0, truncPoint).trim() +
+      "\n\n[Expertise truncada — use agent .md completo se necessario]";
+  }
+
+  return body;
+}
+
+function condenseCodeBlocks(text: string): string {
+  return text.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang: string, code: string) => {
+    const lines = code.split("\n");
+    if (lines.length <= 8) return _match;
+    const kept = lines.slice(0, 6).join("\n");
+    return `\`\`\`${lang}\n${kept}\n// ... (${lines.length - 6} linhas omitidas)\n\`\`\``;
+  });
+}
+
+function findSectionBoundary(text: string, targetLen: number): number {
+  let i = Math.min(targetLen, text.length);
+  const floor = Math.max(0, targetLen - 500);
+  while (i > floor) {
+    if (text[i] === "\n" && text.substring(i + 1, i + 4) === "## ") return i;
+    if (text[i] === "\n" && text.substring(i + 1, i + 5) === "### ") return i;
+    i--;
+  }
+  return targetLen;
+}

package/context/agent-registry.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect } from "bun:test";
+import {
+  AGENT_REGISTRY,
+  resolveAgent,
+  resolveAgentName,
+  suggestAgent,
+  buildAgentDomainMap,
+  getAllAgentNames,
+  getCanonicalAgentNames,
+} from "./agent-registry";
+
+// ── AGENT_REGISTRY structure ─────────────────────────────────
+
+describe("AGENT_REGISTRY", () => {
+  it("contains 11 agents", () => {
+    expect(AGENT_REGISTRY).toHaveLength(11);
+  });
+
+  it("every entry has required fields", () => {
+    for (const entry of AGENT_REGISTRY) {
+      expect(entry.canonical).toBeTruthy();
+      expect(entry.filename).toBeTruthy();
+      expect(entry.domain).toBeTruthy();
+      expect(entry.description).toBeTruthy();
+      expect(Array.isArray(entry.aliases)).toBe(true);
+      expect(entry.aliases.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("filename is always present as alias", () => {
+    for (const entry of AGENT_REGISTRY) {
+      // filename should be resolvable (either as alias or as canonical)
+      const resolved = resolveAgent(entry.filename);
+      expect(resolved).not.toBeNull();
+      expect(resolved!.canonical).toBe(entry.canonical);
+    }
+  });
+
+  it("canonical names are unique", () => {
+    const canonicals = AGENT_REGISTRY.map(e => e.canonical);
+    expect(new Set(canonicals).size).toBe(canonicals.length);
+  });
+});
+
+// ── resolveAgent ─────────────────────────────────────────────
+
+describe("resolveAgent", () => {
+  it("resolves by canonical name", () => {
+    expect(resolveAgent("golang-pro")?.canonical).toBe("golang-pro");
+    expect(resolveAgent("architect")?.canonical).toBe("architect");
+    expect(resolveAgent("backend-javascript")?.canonical).toBe("backend-javascript");
+    expect(resolveAgent("frontend-flutter")?.canonical).toBe("frontend-flutter");
+  });
+
+  it("resolves by filename (alias)", () => {
+    expect(resolveAgent("backend-go")?.canonical).toBe("golang-pro");
+    expect(resolveAgent("backend-csharp")?.canonical).toBe("expert-csharp-developer");
+    expect(resolveAgent("frontend-next")?.canonical).toBe("expert-nextjs-developer");
+    expect(resolveAgent("database-postgres")?.canonical).toBe("expert-postgres-developer");
+    expect(resolveAgent("codexa-architect")?.canonical).toBe("architect");
+  });
+
+  it("resolves by short aliases", () => {
+    expect(resolveAgent("go")?.canonical).toBe("golang-pro");
+    expect(resolveAgent("golang")?.canonical).toBe("golang-pro");
+    expect(resolveAgent("csharp")?.canonical).toBe("expert-csharp-developer");
+    expect(resolveAgent("dotnet")?.canonical).toBe("expert-csharp-developer");
+    expect(resolveAgent("nextjs")?.canonical).toBe("expert-nextjs-developer");
+    expect(resolveAgent("next")?.canonical).toBe("expert-nextjs-developer");
+    expect(resolveAgent("flutter")?.canonical).toBe("frontend-flutter");
+    expect(resolveAgent("dart")?.canonical).toBe("frontend-flutter");
+    expect(resolveAgent("postgres")?.canonical).toBe("expert-postgres-developer");
+    expect(resolveAgent("supabase")?.canonical).toBe("expert-postgres-developer");
+    expect(resolveAgent("security")?.canonical).toBe("security-specialist");
+    expect(resolveAgent("explore")?.canonical).toBe("deep-explore");
+    expect(resolveAgent("arch")?.canonical).toBe("architect");
+  });
+
+  it("is case-insensitive", () => {
+    expect(resolveAgent("GOLANG-PRO")?.canonical).toBe("golang-pro");
+    expect(resolveAgent("Backend-Go")?.canonical).toBe("golang-pro");
+    expect(resolveAgent("FLUTTER")?.canonical).toBe("frontend-flutter");
+  });
+
+  it("returns null for unknown agents", () => {
+    expect(resolveAgent("unknown-agent")).toBeNull();
+    expect(resolveAgent("general-purpose")).toBeNull();
+  });
+
+  it("returns null for empty/null-like input", () => {
+    expect(resolveAgent("")).toBeNull();
+  });
+});
+
+// ── resolveAgentName ─────────────────────────────────────────
+
+describe("resolveAgentName", () => {
+  it("normalizes aliases to canonical", () => {
+    expect(resolveAgentName("backend-go")).toBe("golang-pro");
+    expect(resolveAgentName("nextjs")).toBe("expert-nextjs-developer");
+    expect(resolveAgentName("postgres")).toBe("expert-postgres-developer");
+    expect(resolveAgentName("codexa-architect")).toBe("architect");
+  });
+
+  it("keeps canonical names unchanged", () => {
+    expect(resolveAgentName("golang-pro")).toBe("golang-pro");
+    expect(resolveAgentName("architect")).toBe("architect");
+  });
+
+  it("returns input unchanged if not found (backward compat)", () => {
+    expect(resolveAgentName("custom-agent")).toBe("custom-agent");
+    expect(resolveAgentName("my-special-agent")).toBe("my-special-agent");
+  });
+});
+
+// ── suggestAgent ─────────────────────────────────────────────
+
+describe("suggestAgent", () => {
+  it("suggests for close typos", () => {
+    expect(suggestAgent("golng-pro")).toBe("golang-pro");
+    expect(suggestAgent("backend-goo")).toBe("golang-pro");
+    expect(suggestAgent("testing-unti")).toBe("testing-unit");
+  });
+
+  it("suggests for minor misspellings of aliases", () => {
+    expect(suggestAgent("fluter")).toBe("frontend-flutter");
+    expect(suggestAgent("postgre")).toBe("expert-postgres-developer");
+  });
+
+  it("returns null for very different strings", () => {
+    expect(suggestAgent("xyzxyzxyzxyz")).toBeNull();
+    expect(suggestAgent("completely-unrelated-name")).toBeNull();
+  });
+});
+
+// ── buildAgentDomainMap ──────────────────────────────────────
+
+describe("buildAgentDomainMap", () => {
+  const derived = buildAgentDomainMap();
+
+  it("contains all 11 canonical agents", () => {
+    expect(Object.keys(derived)).toHaveLength(11);
+  });
+
+  it("maps backend agents correctly", () => {
+    expect(derived["golang-pro"]).toBe("backend");
+    expect(derived["expert-csharp-developer"]).toBe("backend");
+    expect(derived["backend-javascript"]).toBe("backend");
+  });
+
+  it("maps frontend agents correctly", () => {
+    expect(derived["expert-nextjs-developer"]).toBe("frontend");
+    expect(derived["frontend-flutter"]).toBe("frontend");
+  });
+
+  it("maps other domains correctly", () => {
+    expect(derived["expert-postgres-developer"]).toBe("database");
+    expect(derived["testing-unit"]).toBe("testing");
+    expect(derived["expert-code-reviewer"]).toBe("review");
+    expect(derived["security-specialist"]).toBe("security");
+    expect(derived["deep-explore"]).toBe("explore");
+    expect(derived["architect"]).toBe("architecture");
+  });
+});
+
+// ── getAllAgentNames / getCanonicalAgentNames ─────────────────
+
+describe("getAllAgentNames", () => {
+  it("includes canonical names", () => {
+    const all = getAllAgentNames();
+    expect(all).toContain("golang-pro");
+    expect(all).toContain("architect");
+  });
+
+  it("includes aliases", () => {
+    const all = getAllAgentNames();
+    expect(all).toContain("backend-go");
+    expect(all).toContain("go");
+    expect(all).toContain("nextjs");
+    expect(all).toContain("flutter");
+  });
+});
+
+describe("getCanonicalAgentNames", () => {
+  it("returns exactly 11 names", () => {
+    expect(getCanonicalAgentNames()).toHaveLength(11);
+  });
+
+  it("contains only canonical names", () => {
+    const canonical = getCanonicalAgentNames();
+    expect(canonical).toContain("golang-pro");
+    expect(canonical).not.toContain("backend-go"); // alias, not canonical
+    expect(canonical).not.toContain("go"); // alias, not canonical
+  });
+});

package/context/agent-registry.ts

@@ -0,0 +1,207 @@
+// ═══════════════════════════════════════════════════════════════
+// AGENT REGISTRY (v9.5)
+// Single source of truth for all agent metadata.
+// Replaces hardcoded AGENT_DOMAIN in domains.ts.
+// ═══════════════════════════════════════════════════════════════
+
+import type { AgentDomain } from "./domains";
+
+export interface AgentEntry {
+  /** Canonical name (= YAML `name` field in agent .md) */
+  canonical: string;
+  /** Filename without .md extension */
+  filename: string;
+  /** Domain for context priority */
+  domain: AgentDomain;
+  /** Human-readable description from YAML frontmatter */
+  description: string;
+  /** Aliases: filename-without-ext, abbreviations */
+  aliases: string[];
+}
+
+export const AGENT_REGISTRY: AgentEntry[] = [
+  {
+    canonical: "golang-pro",
+    filename: "backend-go",
+    domain: "backend",
+    description: "Go senior developer — goroutines, channels, interfaces, net/http 1.22+, error handling with wrapping",
+    aliases: ["backend-go", "go", "golang"],
+  },
+  {
+    canonical: "expert-csharp-developer",
+    filename: "backend-csharp",
+    domain: "backend",
+    description: "C#/.NET senior developer — ASP.NET Core 9+, Entity Framework Core, Minimal APIs, DI, modern C# 12+",
+    aliases: ["backend-csharp", "csharp", "dotnet", "c#"],
+  },
+  {
+    canonical: "backend-javascript",
+    filename: "backend-javascript",
+    domain: "backend",
+    description: "Backend JavaScript/TypeScript developer — Node.js (Express/Fastify) e Bun (Hono/Elysia), APIs REST, middleware",
+    aliases: ["backend-js", "nodejs", "bun-backend"],
+  },
+  {
+    canonical: "expert-nextjs-developer",
+    filename: "frontend-next",
+    domain: "frontend",
+    description: "Next.js 16 developer — App Router, Server Components, Cache Components, Turbopack, React 19.2",
+    aliases: ["frontend-next", "nextjs", "next"],
+  },
+  {
+    canonical: "frontend-flutter",
+    filename: "frontend-flutter",
+    domain: "frontend",
+    description: "Flutter/Dart senior developer — Riverpod, GoRouter, widget composition, platform-specific code",
+    aliases: ["flutter", "dart"],
+  },
+  {
+    canonical: "expert-postgres-developer",
+    filename: "database-postgres",
+    domain: "database",
+    description: "PostgreSQL/Supabase developer — schema design, query optimization, RLS policies, Drizzle ORM",
+    aliases: ["database-postgres", "postgres", "postgresql", "supabase"],
+  },
+  {
+    canonical: "testing-unit",
+    filename: "testing-unit",
+    domain: "testing",
+    description: "Unit testing specialist — Vitest/Jest, Testing Library, mocks, coverage",
+    aliases: ["testing", "unit-test", "vitest", "jest"],
+  },
+  {
+    canonical: "expert-code-reviewer",
+    filename: "expert-code-reviewer",
+    domain: "review",
+    description: "Code reviewer — quality assurance, security analysis, standards compliance, architectural validation",
+    aliases: ["reviewer", "code-reviewer", "review"],
+  },
+  {
+    canonical: "security-specialist",
+    filename: "security-specialist",
+    domain: "security",
+    description: "Security auditor — OWASP Top 10, secrets detection, dependency vulnerabilities, auth/authz",
+    aliases: ["security", "owasp"],
+  },
+  {
+    canonical: "deep-explore",
+    filename: "deep-explore",
+    domain: "explore",
+    description: "Codebase explorer — grepai semantic search, call graph tracing, architecture understanding",
+    aliases: ["explore", "grepai", "search"],
+  },
+  {
+    canonical: "architect",
+    filename: "codexa-architect",
+    domain: "architecture",
+    description: "Software architect — analise, design, decomposicao em baby steps, diagramas Mermaid, ADRs",
+    aliases: ["codexa-architect", "arch"],
+  },
+];
+
+// ── Lookup indexes (built once, O(1) lookups) ────────────────
+
+const byCanonical = new Map<string, AgentEntry>();
+const byAlias = new Map<string, AgentEntry>();
+
+for (const entry of AGENT_REGISTRY) {
+  byCanonical.set(entry.canonical, entry);
+  byAlias.set(entry.canonical, entry);
+  byAlias.set(entry.filename, entry);
+  for (const alias of entry.aliases) {
+    byAlias.set(alias.toLowerCase(), entry);
+  }
+}
+
+/**
+ * Resolve any agent name variant (canonical, filename, alias) to registry entry.
+ * Case-insensitive. Returns null if no match found.
+ */
+export function resolveAgent(name: string): AgentEntry | null {
+  if (!name) return null;
+  const lower = name.toLowerCase();
+  return byCanonical.get(lower) ?? byAlias.get(lower) ?? null;
+}
+
+/**
+ * Resolve agent name to canonical name.
+ * Returns the input unchanged if not found (backward compat).
+ */
+export function resolveAgentName(name: string): string {
+  const entry = resolveAgent(name);
+  return entry ? entry.canonical : name;
+}
+
+/**
+ * Get all valid agent names (canonical + aliases) for validation/suggestions.
+ */
+export function getAllAgentNames(): string[] {
+  return Array.from(byAlias.keys());
+}
+
+/**
+ * Get all canonical agent names.
+ */
+export function getCanonicalAgentNames(): string[] {
+  return AGENT_REGISTRY.map(e => e.canonical);
+}
+
+/**
+ * Did-you-mean suggestion using Levenshtein distance.
+ * Returns the closest canonical name if distance <= 4, else null.
+ */
+export function suggestAgent(input: string): string | null {
+  const lower = input.toLowerCase();
+  let bestMatch: string | null = null;
+  let bestDistance = Infinity;
+
+  for (const name of getAllAgentNames()) {
+    const d = levenshtein(lower, name);
+    if (d < bestDistance) {
+      bestDistance = d;
+      bestMatch = name;
+    }
+  }
+
+  if (bestDistance <= 4 && bestMatch) {
+    const entry = resolveAgent(bestMatch);
+    return entry?.canonical ?? bestMatch;
+  }
+
+  return null;
+}
+
+/**
+ * Derive AGENT_DOMAIN map from registry (backward compat with domains.ts).
+ */
+export function buildAgentDomainMap(): Record<string, AgentDomain> {
+  const map: Record<string, AgentDomain> = {};
+  for (const entry of AGENT_REGISTRY) {
+    map[entry.canonical] = entry.domain;
+  }
+  return map;
+}
+
+// ── Levenshtein (minimal, no deps) ──────────────────────────
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost,
+      );
+    }
+  }
+
+  return dp[m][n];
+}

package/context/domains.test.ts

@@ -298,3 +298,36 @@ describe("AGENT_DOMAIN completeness", () => {
     }
   });
 });
+
+// ── getAgentDomain with aliases (via registry) ───────────────
+
+describe("getAgentDomain with aliases", () => {
+  it("resolves filename aliases to correct domain", () => {
+    expect(getAgentDomain("backend-go")).toBe("backend");
+    expect(getAgentDomain("backend-csharp")).toBe("backend");
+    expect(getAgentDomain("frontend-next")).toBe("frontend");
+    expect(getAgentDomain("database-postgres")).toBe("database");
+    expect(getAgentDomain("codexa-architect")).toBe("architecture");
+  });
+
+  it("resolves short aliases to correct domain", () => {
+    expect(getAgentDomain("go")).toBe("backend");
+    expect(getAgentDomain("golang")).toBe("backend");
+    expect(getAgentDomain("csharp")).toBe("backend");
+    expect(getAgentDomain("dotnet")).toBe("backend");
+    expect(getAgentDomain("nextjs")).toBe("frontend");
+    expect(getAgentDomain("next")).toBe("frontend");
+    expect(getAgentDomain("flutter")).toBe("frontend");
+    expect(getAgentDomain("dart")).toBe("frontend");
+    expect(getAgentDomain("postgres")).toBe("database");
+    expect(getAgentDomain("supabase")).toBe("database");
+    expect(getAgentDomain("security")).toBe("security");
+    expect(getAgentDomain("explore")).toBe("explore");
+    expect(getAgentDomain("arch")).toBe("architecture");
+  });
+
+  it("still returns null for truly unknown names", () => {
+    expect(getAgentDomain("xyz-unknown")).toBeNull();
+    expect(getAgentDomain("general-purpose")).toBeNull();
+  });
+});

package/context/domains.ts

@@ -4,6 +4,7 @@
 // ═══════════════════════════════════════════════════════════════
 
 import type { ContextSection } from "./assembly";
+import { buildAgentDomainMap, resolveAgent } from "./agent-registry";
 
 export type AgentDomain =
   | "backend"
@@ -34,21 +35,9 @@ export type SectionName =
 
 export type DomainProfile = Record<SectionName, Relevance>;
 
-// ── Agent → Domain mapping ───────────────────────────────────
-
-export const AGENT_DOMAIN: Record<string, AgentDomain> = {
-  "backend-javascript":       "backend",
-  "expert-csharp-developer":  "backend",
-  "golang-pro":               "backend",
-  "expert-nextjs-developer":  "frontend",
-  "frontend-flutter":         "frontend",
-  "expert-postgres-developer": "database",
-  "testing-unit":             "testing",
-  "expert-code-reviewer":     "review",
-  "security-specialist":      "security",
-  "deep-explore":             "explore",
-  "architect":                "architecture",
-};
+// ── Agent → Domain mapping (derived from AGENT_REGISTRY) ─────
+
+export const AGENT_DOMAIN: Record<string, AgentDomain> = buildAgentDomainMap();
 
 // ── Domain → Section relevance profiles ──────────────────────
 //
@@ -113,7 +102,11 @@ const RELEVANCE_OFFSET: Record<Relevance, number> = {
 
 export function getAgentDomain(agentName: string | null | undefined): AgentDomain | null {
   if (!agentName) return null;
-  return AGENT_DOMAIN[agentName] ?? null;
+  // Fast path: direct canonical lookup
+  if (AGENT_DOMAIN[agentName]) return AGENT_DOMAIN[agentName];
+  // Resolve alias via registry
+  const entry = resolveAgent(agentName);
+  return entry?.domain ?? null;
 }
 
 export function domainToScope(domain: AgentDomain | null): string {

package/context/index.ts

@@ -22,3 +22,6 @@ export {
 } from "./sections";
 export { findReferenceFiles } from "./references";
 export type { ReferenceFile } from "./references";
+export { AGENT_REGISTRY, resolveAgent, resolveAgentName, suggestAgent, buildAgentDomainMap, getAllAgentNames, getCanonicalAgentNames } from "./agent-registry";
+export type { AgentEntry } from "./agent-registry";
+export { loadAgentExpertise, getAgentDescription, findAgentsDir, clearExpertiseCache } from "./agent-expertise";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexa/cli",
-  "version": "9.0.12",
+  "version": "9.0.13",
   "description": "Orchestrated workflow system for Claude Code - manages feature development through parallel subagents with structured phases, gates, and quality enforcement.",
   "type": "module",
   "bin": {

package/templates/subagent-context.md

@@ -1,9 +1,11 @@
+{{agentIdentity}}
+
 ╔══════════════════════════════════════════════════════════════════════════════╗
 ║  DIRETIVA CRITICA: USE Write/Edit PARA CRIAR OS ARQUIVOS                     ║
 ║  NAO descreva. NAO planeje. NAO simule. EXECUTE AGORA.                       ║
 ║  Se retornar sem usar Write/Edit, a task FALHA.                              ║
 ╚══════════════════════════════════════════════════════════════════════════════╝
-
+{{agentExpertise}}
 ARQUIVOS QUE VOCE DEVE CRIAR (use Write para cada um):
 {{filesList}}