AGENTS.md

AGENTS.md - Synkra AIOX

Este arquivo configura o comportamento esperado de agentes no Codex CLI neste repositorio.

Constitution

Siga .aiox-core/constitution.md como fonte de verdade:

• CLI First
• Agent Authority
• Story-Driven Development
• No Invention
• Quality First
• Absolute Imports

Workflow Obrigatorio

1. Inicie por uma story (path explícito ou discovery):
   • Framework / OSS versionado (este repo): docs/framework/epics/{epic}/
   • Projeto L4 (runtime, tipicamente gitignored aqui): docs/stories/
   • Política: docs/framework/story-locations.md
2. Implemente apenas o que os acceptance criteria pedem
3. Atualize checklist ([ ] -> [x]) e file list
4. Execute quality gates antes de concluir

Quality Gates

npm run lint
npm run typecheck
npm test

Estrutura Principal

• Core framework: .aiox-core/
• CLI: bin/
• Pacotes: packages/
• Testes: tests/
• Documentacao: docs/
• Epics/stories públicos do framework: docs/framework/epics/
• Stories de projeto (L4): docs/stories/ (gitignored neste template)

IDE/Agent Sync

• Sincronizar regras/agentes: npm run sync:ide
• Validar drift: npm run sync:ide:check
• Rodar paridade multi-IDE (Claude/Codex/Gemini): npm run validate:parity
• Sync Claude Code: npm run sync:ide:claude
• Sincronizar Gemini CLI: npm run sync:ide:gemini
• Validar Codex sync/integration: npm run validate:codex-sync && npm run validate:codex-integration
• Gerar skills locais do Codex: npm run sync:skills:codex
• Este repositorio usa local-first: prefira .codex/skills versionado no projeto
• Use sync:skills:codex:global apenas para testes fora deste repo
• Gerar agents/skills/roles do Grok Build: npm run sync:skills:grok
• Artefatos Grok versionados em .grok/ (ver .grok/README.md)

Agent Shortcuts (Grok Build)

Preferencia de ativacao no Grok TUI:

1. Use slash skills: /aiox-dev, /aiox-qa, /aiox-devops, etc. (em .grok/skills/)
2. Workflows: /aiox-sdc, /aiox-quality-gates, /aiox-handoff, /aiox-commit
3. Profiles de sessao/subagent: .grok/agents/aiox-*.md
4. Source of truth continua em .aiox-core/development/agents/

Atalhos Grok (skills):

• /aiox-master · /aiox-analyst · /aiox-architect · /aiox-data-engineer
• /aiox-dev · /aiox-devops · /aiox-pm · /aiox-po
• /aiox-qa · /aiox-sm · /aiox-squad-creator · /aiox-ux-design-expert

Agent Shortcuts (Codex)

Preferencia de ativacao no Codex CLI:

1. Use /skills e selecione aiox-<agent-id> vindo de .codex/skills (ex.: aiox-architect)
2. Se preferir, use os atalhos abaixo (@architect, /architect, etc.)

Quando a mensagem do usuario for um atalho de agente, carregue o arquivo correspondente em .aiox-core/development/agents/ (fallback: .codex/agents/), renderize o greeting via generate-greeting.js e assuma a persona ate receber *exit.

Atalhos aceitos por agente:

• @aiox-master, /aiox-master, /aiox-master.md -> .aiox-core/development/agents/aiox-master.md
• @analyst, /analyst, /analyst.md -> .aiox-core/development/agents/analyst.md
• @architect, /architect, /architect.md -> .aiox-core/development/agents/architect.md
• @data-engineer, /data-engineer, /data-engineer.md -> .aiox-core/development/agents/data-engineer.md
• @dev, /dev, /dev.md -> .aiox-core/development/agents/dev.md
• @devops, /devops, /devops.md -> .aiox-core/development/agents/devops.md
• @pm, /pm, /pm.md -> .aiox-core/development/agents/pm.md
• @po, /po, /po.md -> .aiox-core/development/agents/po.md
• @qa, /qa, /qa.md -> .aiox-core/development/agents/qa.md
• @sm, /sm, /sm.md -> .aiox-core/development/agents/sm.md
• @squad-creator, /squad-creator, /squad-creator.md -> .aiox-core/development/agents/squad-creator.md
• @ux-design-expert, /ux-design-expert, /ux-design-expert.md -> .aiox-core/development/agents/ux-design-expert.md

Resposta esperada ao ativar atalho:

1. Confirmar agente ativado
2. Mostrar 3-6 comandos principais (*help, etc.)
3. Seguir na persona do agente