Skip to content

codex-integration-process.md

Latest commit

 

History

History
170 lines (116 loc) · 5.75 KB

codex-integration-process.md

File metadata and controls

170 lines (116 loc) · 5.75 KB
Raw

Integracao AIOX com Codex CLI (Estado Atual)

Este documento descreve o estado operacional atual da integracao AIOX + Codex CLI no AIOX 4.2.11. O foco aqui nao e historico: e operacao pratica, compatibilidade real e como manter sem regressao.

Resumo Executivo

O Codex hoje e alvo de primeira classe no AIOX:

  • AGENTS.md como contrato operacional do projeto no Codex
  • suporte oficial no installer/sync (codex em ide-configs)
  • skills nativas via .codex/skills com estrategia local-first
  • pipeline canonico de greeting/ativacao compartilhado
  • validadores dedicados para detectar drift rapidamente
  • suporte a notify command e hooks de ferramenta em releases recentes do Codex CLI

Em termos praticos: Codex esta no mesmo trilho arquitetural das integracoes principais do AIOX, sem caminho paralelo legado.

Status de Compatibilidade (AIOX 4.2)

O que você quer fazer Funciona no Codex? Como fazer
Ativar agentes AIOX Works /skills depois escolha aiox-<agent-id>
Sincronizar e validar arquivos AIOX Works npm run sync:ide:codex e npm run validate:codex-sync
Checagens automáticas antes/depois de ações Limited Rode npm run validate:parity manualmente; parte da automação depende de disciplina no fluxo

Regra prática para iniciantes:

  • Se você quer o máximo de automação (checagens automáticas sem precisar rodar comandos), prefira Claude Code ou Gemini CLI.
  • Se você usa Codex, siga o fluxo local-first: ative agentes via /skills e rode os validadores após cada mudança.

Arquitetura Canonica

Fonte de verdade

  • Agentes canonicos: .aiox-core/development/agents/*.md
  • Regras de projeto Codex: AGENTS.md

Pipeline de ativacao

  • Runtime: .aiox-core/development/scripts/activation-runtime.js
  • Entrada de greeting: .aiox-core/development/scripts/generate-greeting.js
  • Contrato: skills e atalhos carregam agente canonico e renderizam greeting via pipeline unificado

Artefatos Codex no projeto

  • Agentes auxiliares: .codex/agents/
  • Skills locais: .codex/skills/aiox-*/SKILL.md

Fluxo Operacional Recomendado

  1. Sincronizar artefatos Codex de projeto:
    • npm run sync:ide:codex
  2. Gerar/atualizar skills locais:
    • npm run sync:skills:codex
  3. Validar consistencia:
    • npm run validate:codex-sync
    • npm run validate:codex-integration
    • npm run validate:codex-skills
    • npm run validate:paths
  4. No Codex, usar /skills e escolher aiox-<agent-id> como ativacao padrao.

Fallback: atalhos definidos em AGENTS.md (@architect, /architect, etc.).

Politica de Escopo (Importante)

Este repositorio usa local-first para skills:

  • preferir .codex/skills versionado no projeto
  • evitar duplicar com ~/.codex/skills
  • usar npm run sync:skills:codex:global apenas quando quiser instalacao global explicitamente

Isso evita menu duplicado no /skills e reduz drift entre equipe/CI.

Guardrails e Anti-Regressao

Comando consolidado de paridade:

  • npm run validate:parity (Claude + Codex + Gemini + guardrails de paths/skills)

Validadores

  • Integracao estrutural: .aiox-core/infrastructure/scripts/validate-codex-integration.js
  • Skills: .aiox-core/infrastructure/scripts/codex-skills-sync/validate.js
  • Paths/contratos: .aiox-core/infrastructure/scripts/validate-paths.js

Smoke test rapido

npm run sync:ide:codex
npm run sync:skills:codex
npm run validate:codex-sync
npm run validate:codex-integration
npm run validate:codex-skills
npm run validate:paths

Criterio de sucesso:

  • AGENTS.md presente e coerente
  • .codex/agents/*.md existente
  • .codex/skills/aiox-*/SKILL.md existente
  • validadores sem erro

Recursos Recentes do Codex (AIOX 4.0)

  • notify command configuravel no config.toml
  • aprovacoes por preset (suggest/auto-edit/full-auto)
  • hooks de ferramenta e de execucao de comandos em evolucao no CLI

No AIOX, o caminho recomendado continua: AGENTS.md + /skills + MCP + scripts de sync/validacao.

Limitacoes de Hooks no Codex (Impacto Real)

Mesmo com melhorias recentes, o Codex ainda nao replica 1:1 o lifecycle de hooks do Claude.

Impactos praticos:

  • menor automacao de eventos de ciclo de sessao (SessionStart/SessionEnd) no padrao AIOX
  • menor capacidade de enforcement automatico em beforeTool/afterTool
  • trilha automatica de auditoria menos rica quando comparada ao fluxo com hooks completos

Mitigacao operacional no AIOX:

  • fortalecer AGENTS.md como contrato de execucao
  • usar /skills como ativacao padrao de agentes
  • usar MCP para contexto e integracoes
  • rodar sync + validadores com disciplina (sync:ide:codex, sync:skills:codex, validate:codex-sync, validate:codex-integration, validate:codex-skills)

Problemas Classicos e Correcao

Skills duplicadas no /skills

Causa tipica:

  • artefatos duplicados entre .codex/skills e ~/.codex/skills

Correcao:

  • manter local-first neste repo
  • evitar sync global durante desenvolvimento local

Greeting diferente entre Codex e outros alvos

Causa tipica:

  • pular pipeline canonico de greeting

Correcao:

  • sempre gerar greeting via generate-greeting.js (runtime unificado)
  • garantir skill apontando para agente canonico em .aiox-core/development/agents/

Drift entre agente canonico e skill

Causa tipica:

  • editar skill manualmente sem resync

Correcao:

  • rodar npm run sync:skills:codex
  • validar com npm run validate:codex-skills

Relacao com a Documentacao Geral

Este documento complementa:

  • AGENTS.md (contrato operacional no Codex)
  • docs/ide-integration.md (visao comparativa por IDE)
  • README.md (quick start e comandos principais)

Se houver divergencia entre estes documentos, a ordem de verdade para operacao de projeto e:

  1. AGENTS.md
  2. scripts reais em package.json
  3. este documento
  4. docs de overview