@codexa/cli 9.0.10 → 9.0.12

package/commands/team.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import {
+  detectPhase,
+  buildLeadSpawnInstruction,
+  buildImpSpawnPrompt,
+  buildRevSpawnPrompt,
+  buildArchitectSpawnPrompt,
+  buildArchitectReviewerPrompt,
+  type TeammateConfig,
+} from "./team";
+
+// ─────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────
+
+function createTestDb(): Database {
+  const db = new Database(":memory:");
+
+  db.run(`CREATE TABLE specs (
+    id TEXT PRIMARY KEY, name TEXT, phase TEXT, approved_at TEXT,
+    analysis_id TEXT, created_at TEXT, updated_at TEXT
+  )`);
+
+  db.run(`CREATE TABLE tasks (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, spec_id TEXT, number INTEGER,
+    name TEXT, depends_on TEXT, can_parallel INTEGER DEFAULT 1,
+    agent TEXT, files TEXT, status TEXT DEFAULT 'pending',
+    checkpoint TEXT, started_at TEXT, completed_at TEXT
+  )`);
+
+  db.run(`CREATE TABLE artifacts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, spec_id TEXT,
+    task_ref INTEGER, path TEXT, action TEXT, created_at TEXT
+  )`);
+
+  db.run(`CREATE TABLE architectural_analyses (
+    id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, status TEXT DEFAULT 'pending'
+  )`);
+
+  db.run(`CREATE TABLE project (
+    id TEXT PRIMARY KEY DEFAULT 'default', stack TEXT,
+    cli_version TEXT, typecheck_command TEXT, grepai_workspace TEXT
+  )`);
+
+  db.run("INSERT INTO project (id) VALUES ('default')");
+
+  return db;
+}
+
+function insertSpec(db: Database, id: string, name: string, phase: string): void {
+  db.run("INSERT INTO specs (id, name, phase, created_at) VALUES (?, ?, ?, datetime('now'))", [id, name, phase]);
+}
+
+function insertTask(
+  db: Database,
+  specId: string,
+  number: number,
+  name: string,
+  options: { agent?: string; canParallel?: boolean; dependsOn?: number[]; status?: string } = {}
+): number {
+  const result = db.run(
+    `INSERT INTO tasks (spec_id, number, name, agent, can_parallel, depends_on, status)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [
+      specId,
+      number,
+      name,
+      options.agent || "general",
+      options.canParallel !== false ? 1 : 0,
+      options.dependsOn ? JSON.stringify(options.dependsOn) : null,
+      options.status || "pending",
+    ]
+  );
+  return Number(result.lastInsertRowid);
+}
+
+function insertArtifact(db: Database, specId: string, taskRef: number, path: string): void {
+  db.run("INSERT INTO artifacts (spec_id, task_ref, path, action) VALUES (?, ?, ?, 'created')", [specId, taskRef, path]);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────
+
+describe("detectPhase", () => {
+  it("detecta imp quando spec.phase = implementing", () => {
+    const db = createTestDb();
+    const spec = { phase: "implementing" };
+    expect(detectPhase(db, spec)).toBe("imp");
+  });
+
+  it("detecta rev quando spec.phase = reviewing", () => {
+    const db = createTestDb();
+    const spec = { phase: "reviewing" };
+    expect(detectPhase(db, spec)).toBe("rev");
+  });
+
+  it("detecta architect quando ha analise pendente", () => {
+    const db = createTestDb();
+    db.run("INSERT INTO architectural_analyses (name, status) VALUES ('test', 'pending')");
+    const spec = { phase: "planning" };
+    expect(detectPhase(db, spec)).toBe("architect");
+  });
+
+  it("retorna phase original se nao ha analise pendente", () => {
+    const db = createTestDb();
+    const spec = { phase: "planning" };
+    expect(detectPhase(db, spec)).toBe("planning");
+  });
+});
+
+describe("buildLeadSpawnInstruction", () => {
+  it("gera instrucao em linguagem natural", () => {
+    const teammates: TeammateConfig[] = [
+      { role: "backend-implementer", domain: "backend", taskIds: [1], spawnPrompt: "test prompt" },
+    ];
+    const instruction = buildLeadSpawnInstruction(teammates, "imp");
+    expect(instruction).toContain("Create an agent team");
+    expect(instruction).toContain("delegate mode");
+  });
+
+  it("inclui nome de todos teammates", () => {
+    const teammates: TeammateConfig[] = [
+      { role: "backend-implementer", domain: "backend", taskIds: [1], spawnPrompt: "p1" },
+      { role: "frontend-implementer", domain: "frontend", taskIds: [2], spawnPrompt: "p2" },
+    ];
+    const instruction = buildLeadSpawnInstruction(teammates, "imp");
+    expect(instruction).toContain("backend-implementer");
+    expect(instruction).toContain("frontend-implementer");
+  });
+
+  it("inclui instrucao de delegate mode", () => {
+    const teammates: TeammateConfig[] = [
+      { role: "test", domain: "test", taskIds: [], spawnPrompt: "p" },
+    ];
+    const instruction = buildLeadSpawnInstruction(teammates, "rev");
+    expect(instruction).toContain("do NOT implement anything yourself");
+  });
+
+  it("usa descricao correta por fase", () => {
+    const tm: TeammateConfig[] = [{ role: "r", domain: "d", taskIds: [], spawnPrompt: "p" }];
+    expect(buildLeadSpawnInstruction(tm, "imp")).toContain("implement parallel tasks");
+    expect(buildLeadSpawnInstruction(tm, "rev")).toContain("review artifacts");
+    expect(buildLeadSpawnInstruction(tm, "architect")).toContain("competing architectural");
+  });
+});
+
+describe("buildImpSpawnPrompt", () => {
+  it("inclui identidade de teammate", () => {
+    const prompt = buildImpSpawnPrompt({ name: "Test Feature" }, "backend", [
+      { number: 1, name: "Task 1", id: 10, files: '["src/a.ts"]' },
+    ]);
+    expect(prompt).toContain("TEAMMATE de implementacao");
+    expect(prompt).toContain("Dominio: backend");
+  });
+
+  it("inclui secao TASK LIST com instrucao de ignorar nativa", () => {
+    const prompt = buildImpSpawnPrompt({ name: "F" }, "backend", [
+      { number: 1, name: "T1", id: 1, files: null },
+    ]);
+    expect(prompt).toContain("TASK LIST");
+    expect(prompt).toContain("IGNORE");
+    expect(prompt).toContain("Codexa tasks");
+  });
+
+  it("inclui instrucao de messaging nativo", () => {
+    const prompt = buildImpSpawnPrompt({ name: "F" }, "backend", [
+      { number: 1, name: "T1", id: 1, files: null },
+    ]);
+    expect(prompt).toContain("ferramenta `message`");
+    expect(prompt).toContain("codexa knowledge add");
+  });
+
+  it("lista todas tasks atribuidas", () => {
+    const prompt = buildImpSpawnPrompt({ name: "F" }, "backend", [
+      { number: 1, name: "Create schema", id: 10, files: '["db/schema.ts"]' },
+      { number: 2, name: "Add migration", id: 11, files: null },
+    ]);
+    expect(prompt).toContain("Task #1: Create schema");
+    expect(prompt).toContain("Task #2: Add migration");
+  });
+});
+
+describe("buildRevSpawnPrompt", () => {
+  it("inclui lente correta", () => {
+    const prompt = buildRevSpawnPrompt({ name: "F" }, "security", ["src/a.ts"]);
+    expect(prompt).toContain("**SECURITY**");
+    expect(prompt).toContain("OWASP");
+  });
+
+  it("inclui instrucao de message para enviar findings", () => {
+    const prompt = buildRevSpawnPrompt({ name: "F" }, "performance", ["src/a.ts"]);
+    expect(prompt).toContain("ferramenta `message`");
+  });
+
+  it("inclui instrucao de ignorar task list nativa", () => {
+    const prompt = buildRevSpawnPrompt({ name: "F" }, "standards", ["src/a.ts"]);
+    expect(prompt).toContain("IGNORE a task list nativa");
+  });
+
+  it("lista artefatos para revisao", () => {
+    const prompt = buildRevSpawnPrompt({ name: "F" }, "security", ["src/a.ts", "src/b.ts"]);
+    expect(prompt).toContain("- src/a.ts");
+    expect(prompt).toContain("- src/b.ts");
+  });
+});
+
+describe("buildArchitectSpawnPrompt", () => {
+  it("inclui identidade de architect", () => {
+    const prompt = buildArchitectSpawnPrompt({ name: "Add auth" }, {}, "alpha");
+    expect(prompt).toContain("ARCHITECT ALPHA");
+  });
+
+  it("inclui instrucao de message para proposta", () => {
+    const prompt = buildArchitectSpawnPrompt({ name: "Add auth" }, {}, "beta");
+    expect(prompt).toContain("ferramenta `message`");
+    expect(prompt).toContain("Enviar ao Lead");
+  });
+
+  it("inclui 8 headers obrigatorios", () => {
+    const prompt = buildArchitectSpawnPrompt({ name: "Add auth" }, {}, "alpha");
+    expect(prompt).toContain("Contexto e Entendimento");
+    expect(prompt).toContain("Baby Steps");
+    expect(prompt).toContain("Decisoes Arquiteturais");
+  });
+});
+
+describe("buildArchitectReviewerPrompt", () => {
+  it("inclui explicacao de entrega automatica de mensagens", () => {
+    const prompt = buildArchitectReviewerPrompt({ name: "Add auth" });
+    expect(prompt).toContain("entregues automaticamente");
+    expect(prompt).toContain("sem precisar");
+    expect(prompt).toContain("polling");
+  });
+
+  it("instrui a aguardar AMBAS propostas", () => {
+    const prompt = buildArchitectReviewerPrompt({ name: "Add auth" });
+    expect(prompt).toContain("AMBAS as propostas");
+  });
+
+  it("inclui formato estruturado de critica", () => {
+    const prompt = buildArchitectReviewerPrompt({ name: "Add auth" });
+    expect(prompt).toContain("Pontos Fortes");
+    expect(prompt).toContain("Pontos Fracos");
+    expect(prompt).toContain("FORTE | VIAVEL | FRACO");
+  });
+
+  it("inclui instrucao de IGNORE task list nativa", () => {
+    const prompt = buildArchitectReviewerPrompt({ name: "Add auth" });
+    expect(prompt).toContain("IGNORE a task list nativa");
+  });
+});

package/commands/team.ts

@@ -0,0 +1,703 @@
+import { getDb } from "../db/connection";
+import { initSchema } from "../db/schema";
+import { resolveSpec, resolveSpecOrNull } from "./spec-resolver";
+
+// ─────────────────────────────────────────────────────────────────
+// Interfaces
+// ─────────────────────────────────────────────────────────────────
+
+export interface TeammateConfig {
+  role: string;
+  domain: string;
+  taskIds: number[];
+  spawnPrompt: string;
+}
+
+export interface TeamSuggestion {
+  recommended: boolean;
+  mode: "team" | "subagent";
+  reason: string;
+  envVarSet: boolean;
+  teamConfig?: {
+    phase: "imp" | "rev" | "architect";
+    teammates: TeammateConfig[];
+    estimatedParallelism: number;
+    leadSpawnInstruction: string;
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Main Command
+// ─────────────────────────────────────────────────────────────────
+
+export function teamSuggest(options: {
+  json?: boolean;
+  phase?: string;
+  spec?: string;
+}): void {
+  initSchema();
+  const db = getDb();
+
+  const envVarSet = process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === "1";
+
+  // Phase pode ser fornecida ou detectada
+  let spec: any = null;
+  let phase = options.phase;
+
+  if (!phase) {
+    spec = resolveSpecOrNull(options.spec);
+    if (spec) {
+      phase = detectPhase(db, spec);
+    } else {
+      phase = "unknown";
+    }
+  } else {
+    spec = resolveSpecOrNull(options.spec);
+  }
+
+  let result: TeamSuggestion;
+
+  if (phase === "imp" && spec) {
+    result = suggestForImp(db, spec, envVarSet);
+  } else if (phase === "rev" && spec) {
+    result = suggestForRev(db, spec, envVarSet);
+  } else if (phase === "architect") {
+    result = suggestForArchitect(db, spec, envVarSet);
+  } else {
+    result = {
+      recommended: false,
+      mode: "subagent",
+      reason: `Fase atual (${phase}) nao suporta teams.`,
+      envVarSet,
+    };
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printTeamSuggestion(result);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Phase Detection
+// ─────────────────────────────────────────────────────────────────
+
+export function detectPhase(db: any, spec: any): string {
+  if (spec.phase === "implementing") return "imp";
+  if (spec.phase === "reviewing") return "rev";
+
+  // Verificar se ha analise arquitetural pendente
+  const pendingAnalysis = db
+    .query("SELECT id FROM architectural_analyses WHERE status = 'pending' LIMIT 1")
+    .get();
+  if (pendingAnalysis) return "architect";
+
+  return spec.phase;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// IMP Phase
+// ─────────────────────────────────────────────────────────────────
+
+function suggestForImp(db: any, spec: any, envVarSet: boolean): TeamSuggestion {
+  // 1. Buscar tasks pending com dependencias satisfeitas
+  const allTasks = db
+    .query("SELECT * FROM tasks WHERE spec_id = ? AND status = 'pending'")
+    .all(spec.id) as any[];
+
+  const available = allTasks.filter((t: any) => {
+    if (!t.depends_on) return true;
+    const deps = JSON.parse(t.depends_on) as number[];
+    return deps.every((depNum) => {
+      const dep = db
+        .query("SELECT status FROM tasks WHERE spec_id = ? AND number = ?")
+        .get(spec.id, depNum) as any;
+      return dep?.status === "done";
+    });
+  });
+
+  const parallelizable = available.filter((t: any) => t.can_parallel);
+
+  // 2. Agrupar por dominio (campo agent)
+  const byDomain = new Map<string, any[]>();
+  for (const task of parallelizable) {
+    const domain = task.agent || "general";
+    if (!byDomain.has(domain)) byDomain.set(domain, []);
+    byDomain.get(domain)!.push(task);
+  }
+
+  // 3. Recomendar se >= 3 tasks em >= 2 dominios
+  if (parallelizable.length < 3 || byDomain.size < 2) {
+    return {
+      recommended: false,
+      mode: "subagent",
+      reason: `${parallelizable.length} tasks paralelas em ${byDomain.size} dominio(s). Minimo: 3 tasks, 2 dominios.`,
+      envVarSet,
+    };
+  }
+
+  if (!envVarSet) {
+    return {
+      recommended: true,
+      mode: "subagent",
+      reason: "Team recomendado mas CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS nao definida. Usando subagent.",
+      envVarSet: false,
+    };
+  }
+
+  // 4. Gerar teammates
+  const teammates: TeammateConfig[] = [];
+  for (const [domain, tasks] of byDomain) {
+    teammates.push({
+      role: `${domain}-implementer`,
+      domain,
+      taskIds: tasks.map((t: any) => t.id),
+      spawnPrompt: buildImpSpawnPrompt(spec, domain, tasks),
+    });
+  }
+
+  return {
+    recommended: true,
+    mode: "team",
+    reason: `${parallelizable.length} tasks paralelas em ${byDomain.size} dominios.`,
+    envVarSet: true,
+    teamConfig: {
+      phase: "imp",
+      teammates,
+      estimatedParallelism: parallelizable.length,
+      leadSpawnInstruction: buildLeadSpawnInstruction(teammates, "imp"),
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// REV Phase
+// ─────────────────────────────────────────────────────────────────
+
+function suggestForRev(db: any, spec: any, envVarSet: boolean): TeamSuggestion {
+  const totalTasks = (db
+    .query("SELECT COUNT(*) as count FROM tasks WHERE spec_id = ?")
+    .get(spec.id) as any).count;
+
+  const artifactCount = (db
+    .query("SELECT COUNT(*) as count FROM artifacts WHERE spec_id = ?")
+    .get(spec.id) as any).count;
+
+  if (totalTasks < 3 && artifactCount < 5) {
+    return {
+      recommended: false,
+      mode: "subagent",
+      reason: `${totalTasks} tasks, ${artifactCount} artefatos. Reviewer unico suficiente.`,
+      envVarSet,
+    };
+  }
+
+  if (!envVarSet) {
+    return {
+      recommended: true,
+      mode: "subagent",
+      reason: "Team recomendado mas env var nao definida.",
+      envVarSet: false,
+    };
+  }
+
+  const artifactList = (db
+    .query("SELECT path FROM artifacts WHERE spec_id = ?")
+    .all(spec.id) as any[]).map((a: any) => a.path);
+
+  const lenses = ["security", "performance", "standards"] as const;
+  const teammates: TeammateConfig[] = lenses.map((lens) => ({
+    role: `${lens}-reviewer`,
+    domain: "review",
+    taskIds: [],
+    spawnPrompt: buildRevSpawnPrompt(spec, lens, artifactList),
+  }));
+
+  return {
+    recommended: true,
+    mode: "team",
+    reason: `${totalTasks} tasks, ${artifactCount} artefatos. 3 reviewers recomendados.`,
+    envVarSet: true,
+    teamConfig: {
+      phase: "rev",
+      teammates,
+      estimatedParallelism: 3,
+      leadSpawnInstruction: buildLeadSpawnInstruction(teammates, "rev"),
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Architect Phase
+// ─────────────────────────────────────────────────────────────────
+
+function suggestForArchitect(db: any, spec: any, envVarSet: boolean): TeamSuggestion {
+  const analysis = db
+    .query("SELECT * FROM architectural_analyses WHERE status = 'pending' ORDER BY id DESC LIMIT 1")
+    .get() as any;
+
+  if (!analysis) {
+    return {
+      recommended: false,
+      mode: "subagent",
+      reason: "Nenhuma analise arquitetural pendente.",
+      envVarSet,
+    };
+  }
+
+  if (!envVarSet) {
+    return {
+      recommended: true,
+      mode: "subagent",
+      reason: "Team recomendado mas env var nao definida.",
+      envVarSet: false,
+    };
+  }
+
+  const project = db.query("SELECT * FROM project LIMIT 1").get() as any;
+  const stackSummary = project?.stack ? JSON.parse(project.stack) : {};
+
+  const teammates: TeammateConfig[] = [
+    {
+      role: "architect-alpha",
+      domain: "architecture",
+      taskIds: [],
+      spawnPrompt: buildArchitectSpawnPrompt(analysis, stackSummary, "alpha"),
+    },
+    {
+      role: "architect-beta",
+      domain: "architecture",
+      taskIds: [],
+      spawnPrompt: buildArchitectSpawnPrompt(analysis, stackSummary, "beta"),
+    },
+    {
+      role: "architect-reviewer",
+      domain: "architecture",
+      taskIds: [],
+      spawnPrompt: buildArchitectReviewerPrompt(analysis),
+    },
+  ];
+
+  return {
+    recommended: true,
+    mode: "team",
+    reason: `Analise "${analysis.name}" pendente. Hipoteses competidoras recomendadas.`,
+    envVarSet: true,
+    teamConfig: {
+      phase: "architect",
+      teammates,
+      estimatedParallelism: 3,
+      leadSpawnInstruction: buildLeadSpawnInstruction(teammates, "architect"),
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Lead Spawn Instruction (natural language)
+// ─────────────────────────────────────────────────────────────────
+
+export function buildLeadSpawnInstruction(teammates: TeammateConfig[], phase: string): string {
+  const phaseDescriptions: Record<string, string> = {
+    imp: "implement parallel tasks",
+    rev: "review artifacts with specialized lenses",
+    architect: "propose competing architectural approaches",
+  };
+
+  const teammateLines = teammates.map((t) =>
+    `- "${t.role}" with the prompt: "${t.spawnPrompt.replace(/"/g, '\\"').substring(0, 200)}..."`
+  ).join("\n");
+
+  return `Create an agent team to ${phaseDescriptions[phase] || phase}. Spawn these teammates:
+
+${teammateLines}
+
+Use delegate mode — do NOT implement anything yourself. Only coordinate, monitor messages, and synthesize results.
+Wait for all teammates to finish before proceeding.`;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Spawn Prompts: IMP
+// ─────────────────────────────────────────────────────────────────
+
+export function buildImpSpawnPrompt(spec: any, domain: string, tasks: any[]): string {
+  const taskList = tasks.map((t: any) =>
+    `- Task #${t.number}: ${t.name} (ID: ${t.id}, arquivos: ${t.files || "a definir"})`
+  ).join("\n");
+
+  return `## IDENTIDADE
+
+Voce e um TEAMMATE de implementacao do Codexa Workflow.
+Voce NAO e o orquestrador. Voce NAO coordena. Voce EXECUTA tasks.
+Dominio: ${domain}
+
+## FEATURE
+
+${spec.name}
+
+## SUAS TASKS
+
+${taskList}
+
+## INSTRUCOES
+
+Para CADA task atribuida a voce, execute na ordem:
+
+### 1. Iniciar Task
+\`\`\`bash
+codexa task start <TASK_ID> --json
+\`\`\`
+Leia o \`subagentContext\` e \`context\` retornados. Estes sao suas instrucoes de implementacao.
+
+### 2. Implementar
+Use \`Read\`, \`Write\`, \`Edit\` para criar/modificar os arquivos listados.
+
+**Regras de implementacao**:
+- Siga os standards REQUIRED recebidos no contexto
+- A cada 3 arquivos modificados, verifique blockers:
+  \`\`\`bash
+  codexa knowledge list --severity critical --unread
+  \`\`\`
+- Se encontrar blocker critico: envie \`message\` ao lead explicando e PARE
+
+### 3. Completar Task
+\`\`\`bash
+codexa task done <TASK_ID> --output '{"status":"completed","summary":"descricao do que foi feito","files_created":["..."],"files_modified":["..."],"reasoning":{"approach":"como abordou o problema (min 20 chars)"}}'
+\`\`\`
+
+### 4. Comunicar
+Apos completar cada task, comunique via Agent Teams messaging (nativo):
+- **Mensagem ao lead**: Use a ferramenta \`message\` para enviar resumo da task completada ao lead
+- **Mensagem a outro teammate**: Use a ferramenta \`message\` para enviar diretamente ao teammate afetado
+- **Persistir knowledge**: Para discoveries relevantes alem desta sessao:
+  \`\`\`bash
+  codexa knowledge add --content "DISCOVERY: descricao" --category discovery --severity info
+  \`\`\`
+
+> **IMPORTANTE**: Use \`message\` (nativo Agent Teams) para comunicacao entre sessoes.
+> Use \`codexa knowledge add\` (CLI) para persistir informacao no SQLite para futuras tasks.
+> Ambos sao complementares — messaging e instantaneo, knowledge e persistente.
+
+### 5. Proxima Task
+Apos completar, prossiga para a proxima task da sua lista.
+Se todas suas tasks estao done, envie mensagem ao lead via \`message\` informando conclusao.
+
+## TASK LIST — REGRA CRITICA
+
+Existem DUAS task lists neste ambiente:
+1. **Codexa tasks** (SQLite, via CLI): Esta e a source of truth. Use \`codexa task start/done\`.
+2. **Task list nativa** (Agent Teams): Usada APENAS pelo lead para coordenacao.
+
+**Voce como teammate**: Use SOMENTE Codexa tasks (\`codexa task start\`, \`codexa task done\`).
+NAO interaja com a task list nativa do Agent Teams — o lead gerencia ela.
+
+## CONTEXTO ON-DEMAND
+
+Se precisar de mais contexto alem do minimal:
+\`\`\`bash
+codexa context detail standards    # Regras do projeto
+codexa context detail decisions    # Decisoes anteriores
+codexa context detail patterns     # Patterns de codigo
+codexa context detail knowledge    # Knowledge de outras tasks
+codexa context detail architecture # Analise arquitetural
+\`\`\`
+
+## REGRAS ABSOLUTAS
+
+1. SEMPRE use \`codexa task start\` ANTES de implementar (gates de qualidade)
+2. SEMPRE use \`codexa task done --output\` APOS implementar (gates enforced)
+3. NUNCA modifique arquivos de tasks de outros teammates
+4. SEMPRE inclua \`reasoning.approach\` no retorno (minimo 20 chars — Gate 4.4)
+5. Se bloqueado: envie \`message\` ao lead com contexto completo
+6. Registre discoveries: \`codexa knowledge add\` (persistente) + \`message\` ao afetado (instantaneo)
+7. NAO tente coordenar outros teammates — isso e papel do lead
+8. Use SOMENTE Codexa tasks (CLI) — IGNORE a task list nativa do Agent Teams
+9. Comunicacao entre sessoes: SEMPRE via ferramentas \`message\`/\`broadcast\` do Agent Teams`;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Spawn Prompts: REV
+// ─────────────────────────────────────────────────────────────────
+
+export function buildRevSpawnPrompt(spec: any, lens: string, artifactPaths: string[]): string {
+  const lensDescriptions: Record<string, string> = {
+    security: "SEGURANCA: OWASP Top 10 (injection, XSS, SSRF, CSRF), autenticacao/autorizacao (JWT, sessions, RBAC), secrets hardcoded, dependencias com vulnerabilidades, sanitizacao de input, file access, HTTP headers",
+    performance: "PERFORMANCE: N+1 queries, SELECT * sem necessidade, memory leaks, falta de memoizacao, queries sem index, renderizacoes desnecessarias (React), bundle size, lazy loading ausente, cache strategies",
+    standards: "STANDARDS E QUALIDADE: Conformidade com standards REQUIRED do projeto, DRY (utilities duplicadas), naming conventions, patterns do projeto seguidos, TypeScript types (sem 'any' injustificado), cobertura de testes, tratamento de erros",
+  };
+
+  return `## IDENTIDADE
+
+Voce e um TEAMMATE revisor do Codexa Workflow.
+Sua lente de analise: **${lens.toUpperCase()}**
+Voce NAO modifica codigo. Voce ANALISA e REPORTA.
+
+## FEATURE REVISADA
+
+${spec.name}
+
+## SUA LENTE
+
+${lensDescriptions[lens] || lens}
+
+## ARTEFATOS PARA REVISAO
+
+${artifactPaths.map((p) => `- ${p}`).join("\n")}
+
+## INSTRUCOES
+
+### 1. Obter Contexto
+\`\`\`bash
+codexa review start --json
+codexa context detail standards
+\`\`\`
+
+### 2. Ler Artefatos
+Leia CADA arquivo listado acima usando a ferramenta Read.
+
+### 3. Analisar com Sua Lente
+Aplique APENAS sua lente (${lens}). NAO repita analises de outras lentes.
+Para cada arquivo, identifique problemas por severidade.
+
+### 4. Enviar Findings ao Lead
+Use a ferramenta \`message\` (nativa do Agent Teams) para enviar ao lead no formato:
+
+\`\`\`
+## [${lens.toUpperCase()}] Review — ${spec.name}
+
+### Criticos (bloqueiam aprovacao)
+- [arquivo:linha] Problema. Remediacao sugerida.
+
+### Altos (recomenda bloqueio)
+- [arquivo:linha] Problema.
+
+### Medios (warning)
+- [arquivo:linha] Observacao.
+
+### Baixos (sugestao)
+- [arquivo:linha] Melhoria opcional.
+
+### Resultado: APROVADO | REPROVADO | RESSALVAS
+Justificativa: ...
+\`\`\`
+
+### 5. Registrar Knowledge
+Para cada finding CRITICO ou ALTO:
+\`\`\`bash
+codexa knowledge add --content "REVIEW [${lens}]: problema em arquivo:linha" --category discovery --severity warning
+\`\`\`
+
+## COMUNICACAO
+
+- **Enviar findings ao lead**: Use a ferramenta \`message\` (nativa Agent Teams)
+- **Persistir findings criticos**: Use \`codexa knowledge add\` (CLI) para SQLite
+- NAO use a task list nativa do Agent Teams — apenas o lead gerencia ela
+
+## REGRAS
+
+1. NAO modifique nenhum arquivo
+2. Analise APENAS com sua lente (${lens})
+3. Seja ESPECIFICO: arquivo, linha, problema, sugestao de correcao
+4. Envie TODOS os findings ao lead via ferramenta \`message\`
+5. Registre findings criticos/altos via \`codexa knowledge add\` (persistencia SQLite)
+6. IGNORE a task list nativa do Agent Teams`;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Spawn Prompts: Architect
+// ─────────────────────────────────────────────────────────────────
+
+export function buildArchitectSpawnPrompt(analysis: any, stackSummary: any, role: string): string {
+  return `## IDENTIDADE
+
+Voce e o ARCHITECT ${role.toUpperCase()} do Codexa Workflow.
+Voce propoe UMA abordagem INDEPENDENTE para o problema.
+NAO consulte propostas de outros architects antes de formular a sua.
+
+## PROBLEMA
+
+${analysis.name}
+
+## STACK ATUAL
+
+${JSON.stringify(stackSummary, null, 2)}
+
+## INSTRUCOES
+
+### 1. Explorar Codebase
+Use grepai para pesquisa semantica:
+\`\`\`bash
+grepai search "architecture layers and boundaries" --json --compact
+grepai search "integration points for: ${analysis.name}" --json --compact
+\`\`\`
+
+Tambem use \`grepai trace\` para entender call graphs.
+
+### 2. Contextualizar
+\`\`\`bash
+codexa context detail standards
+codexa context detail architecture
+codexa context detail patterns
+\`\`\`
+
+### 3. Propor Abordagem
+
+Crie sua proposta seguindo os 8 headers OBRIGATORIOS:
+
+1. **## Contexto e Entendimento** — O que voce entendeu do problema
+2. **## Stack e Arquitetura Atual** — Estado atual do sistema
+3. **## Solucao Proposta** — SUA abordagem unica com justificativa
+4. **## Diagramas** — Minimo 2 diagramas Mermaid (arquitetura + fluxo)
+5. **## Baby Steps** — Passos atomicos (1-3 arquivos cada), formato:
+   ### N. Nome
+   **O que**: descricao
+   **Por que**: justificativa
+   **Resultado**: output esperado
+   **Arquivos**: lista
+   **Agente**: backend|frontend|database|testing|general
+   **Depende de**: N (ou nenhum)
+6. **## Riscos e Mitigacoes** — Trade-offs explicitos
+7. **## Alternativas Descartadas** — O que voce considerou e descartou
+8. **## Decisoes Arquiteturais** — ADRs (Architecture Decision Records)
+
+### 4. Enviar ao Lead
+Use a ferramenta \`message\` (nativa Agent Teams) para enviar proposta completa ao lead.
+
+### 5. Responder Criticas
+Voce recebera criticas do Architect Reviewer via \`message\` (entrega automatica).
+- Responda via \`message\` ao Architect Reviewer com justificativas tecnicas
+- Reconheca pontos fracos legitimos
+- Proponha ajustes se necessario
+- Envie versao revisada ao lead via \`message\`
+
+## COMUNICACAO
+
+- **Proposta ao lead**: ferramenta \`message\` (nativa Agent Teams)
+- **Resposta a criticas**: ferramenta \`message\` ao Architect Reviewer
+- **NAO** leia arquivos criados por outros architects (independencia)
+- **NAO** use a task list nativa do Agent Teams
+
+## REGRAS
+
+1. Proposta INDEPENDENTE — nao leia propostas de outros antes
+2. NUNCA escreva codigo de implementacao
+3. Minimo 2 diagramas Mermaid
+4. Baby steps atomicos (1-3 arquivos cada)
+5. Trade-offs EXPLICITOS para cada decisao
+6. Considere escalabilidade, manutenibilidade, seguranca
+7. Comunicacao SOMENTE via ferramenta \`message\` do Agent Teams`;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Spawn Prompts: Architect Reviewer
+// ─────────────────────────────────────────────────────────────────
+
+export function buildArchitectReviewerPrompt(analysis: any): string {
+  return `## IDENTIDADE
+
+Voce e o ARCHITECT REVIEWER do Codexa Workflow.
+Seu papel e DESAFIAR propostas arquiteturais, encontrando pontos fracos,
+riscos nao considerados, e alternativas melhores.
+
+## PROBLEMA EM ANALISE
+
+${analysis.name}
+
+## INSTRUCOES
+
+### 1. Aguardar Propostas
+Propostas dos architects (alpha e beta) serao entregues automaticamente via
+o sistema de messaging do Agent Teams. Voce recebera as mensagens sem precisar
+fazer polling — o Agent Teams entrega mensagens automaticamente na sua sessao.
+Aguarde ate receber AMBAS as propostas antes de iniciar a critica.
+
+### 2. Analisar Criticamente CADA Proposta
+
+Para cada proposta, avalie:
+- **Viabilidade**: A solucao e realista para o contexto?
+- **Escalabilidade**: Funciona com 10x mais dados/usuarios?
+- **Manutenibilidade**: Outro dev entende em 6 meses?
+- **Seguranca**: Ha vetores de ataque nao considerados?
+- **Complexidade**: E a solucao mais simples possivel?
+- **Trade-offs ocultos**: Que custos nao foram mencionados?
+- **Baby steps**: Sao realmente atomicos? Dependencias corretas?
+
+### 3. Enviar Criticas ao Lead
+
+Para CADA proposta, use a ferramenta \`message\` para enviar critica estruturada ao lead:
+
+\`\`\`
+## Critica: Proposta [ALPHA/BETA]
+
+### Pontos Fortes
+- ...
+
+### Pontos Fracos
+- ...
+
+### Riscos Nao Considerados
+- ...
+
+### Perguntas para o Architect
+- ...
+
+### Veredito: FORTE | VIAVEL | FRACO
+Justificativa: ...
+\`\`\`
+
+### 4. Enviar Criticas aos Architects
+
+Apos criticar cada proposta, envie tambem via \`message\` ao architect correspondente
+para que ele possa defender/ajustar sua proposta.
+
+### 5. Recomendar ao Lead
+
+Apos criticar ambas e receber defesas, envie recomendacao final ao lead via \`message\`:
+- Qual proposta e mais robusta e por que
+- Sugestoes de melhoria combinando elementos de ambas
+- Riscos que persistem independente da escolha
+
+## COMUNICACAO
+
+- **Receber propostas**: Automatico via Agent Teams messaging (sem polling)
+- **Enviar criticas ao lead**: ferramenta \`message\`
+- **Enviar criticas aos architects**: ferramenta \`message\` direta ao architect
+- **NAO** use a task list nativa do Agent Teams
+
+## REGRAS
+
+1. Seja JUSTO — critique com fundamento, nao por criticar
+2. NAO proponha sua propria solucao — apenas critique
+3. Base criticas em principios de engenharia (SOLID, KISS, YAGNI)
+4. Considere o contexto real do projeto (stack, team size, constraints)
+5. Comunicacao SOMENTE via ferramenta \`message\` do Agent Teams
+6. IGNORE a task list nativa do Agent Teams`;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Output Formatting
+// ─────────────────────────────────────────────────────────────────
+
+function printTeamSuggestion(result: TeamSuggestion): void {
+  console.log(`\n${"─".repeat(50)}`);
+  console.log(`Agent Teams - Sugestao`);
+  console.log(`${"─".repeat(50)}`);
+
+  console.log(`  Recomendado: ${result.recommended ? "SIM" : "NAO"}`);
+  console.log(`  Modo: ${result.mode}`);
+  console.log(`  Env var: ${result.envVarSet ? "definida" : "NAO definida"}`);
+  console.log(`  Motivo: ${result.reason}`);
+
+  if (result.teamConfig) {
+    const tc = result.teamConfig;
+    console.log(`\n  Fase: ${tc.phase}`);
+    console.log(`  Paralelismo: ${tc.estimatedParallelism}`);
+    console.log(`  Teammates (${tc.teammates.length}):`);
+    for (const tm of tc.teammates) {
+      const taskInfo = tm.taskIds.length > 0 ? ` [tasks: ${tm.taskIds.join(",")}]` : "";
+      console.log(`    - ${tm.role} (${tm.domain})${taskInfo}`);
+    }
+  }
+
+  console.log(`\n${"─".repeat(50)}\n`);
+}

package/package.json

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

package/workflow.ts

@@ -40,6 +40,7 @@ import {
   architectExport,
   architectCancel,
 } from "./commands/architect";
+import { teamSuggest } from "./commands/team";
 import { initSchema } from "./db/schema";
 import { getDb, closeDb } from "./db/connection";
 import { execSync } from "child_process";
@@ -987,6 +988,22 @@ architectCmd
     architectCancel(options);
   });
 
+// ═══════════════════════════════════════════════════════════════
+// AGENT TEAMS (Experimental)
+// ═══════════════════════════════════════════════════════════════
+
+const teamCmd = program.command("team").description("Comandos de Agent Teams (experimental)");
+
+teamCmd
+  .command("suggest")
+  .description("Sugere modo de execucao (team vs subagent) para a fase atual")
+  .option("--json", "Saida em JSON")
+  .option("--phase <phase>", "Fase especifica (imp, rev, architect)")
+  .option("--spec <id>", "ID do spec (padrao: mais recente)")
+  .action(wrapAction((options) => {
+    teamSuggest(options);
+  }));
+
 // ═══════════════════════════════════════════════════════════════
 // PLUGIN
 // ═══════════════════════════════════════════════════════════════