izanagi-ai

Izanagi AI

v3.24.14 · npm estável: 3.24.14. Runtime de execução de trabalho orientado a agentes. Executa sem API key e sem modelo local: se você já tem o claude (Claude Code CLI) instalado e autenticado, izanagi run faz trabalho de verdade usando essa autenticação, por subprocesso.

Arquitetura: Commander → contrato de tarefa → roteamento por papel (por TAREFA, não por run) → grafo → verificação por evidência → healing → replan → memória. O run lê o projeto antes de decidir e entrega arquivo no fim, os dois por nós de tool com permissão declarada. Todo teto declarado (tokens, custo, tempo, retries, agentes, tool calls, concorrência, allowlist de tool) é aplicado e tem teste que mede o teto; Ctrl-C cancela o run e o resume retoma do último batch gravado. 23 agentes especializados, incluindo um coordenador orchestration-only, catálogo de skills v2, CLI publicada no npm (izanagi-ai), SDK programático e topologia poliglota (Rust · Go · Python · TypeScript) ao lado do runtime legado.

Filosofia: Arquitetura primeiro. Código depois. Qualidade medida. Evolução contínua. Zero "cara de IA".

Instalação

Requisito: Node.js ≥ 18.

npm install -g izanagi-ai    # instalação global
npx izanagi <comando>        # ou execução direta sem instalar
izanagi --version

O pacote é publicado como izanagi-ai; bins: izanagi e izanagi-ai.

Executar sem API key

O Izanagi precisa de um executor: alguém que rode os nós do grafo. Existem três caminhos, e o primeiro não pede chave nenhuma.

izanagi doctor     # diz qual executor está disponível AGORA

Caminho	O que exige	Como o runtime o chama
CLI de agente (recomendado)	um agente de codificação já instalado e autenticado: hoje o claude no PATH	provider claude-cli, por subprocesso em modo print. Zero configuração: detectado no PATH
API key	IZANAGI_ANTHROPIC_API_KEY, IZANAGI_OPENAI_API_KEY, IZANAGI_GOOGLE_API_KEY, IZANAGI_OPENROUTER_API_KEY	HTTP direto no provider
Modelo local	IZANAGI_OLLAMA_ENABLED=1 ou IZANAGI_LMSTUDIO_ENABLED=1	endpoint OpenAI-compatible em localhost

Sem nenhum dos três, o run continua funcionando em modo headless: planeja, roteia e verifica de verdade, mas SIMULA o conteúdo dos nós. É o comportamento antigo, e agora ele é o último recurso, não o default de quem nunca configurou nada.

# nada além do Claude Code instalado:
izanagi run "Escreva a função validarCPF em TypeScript" --output out
#   ✔ Execução real: claude-cli
#     via CLI de agente já autenticado (sem API key)
#     tools do executor: none (--agent-tools read liga leitura do repositório)

Os agentes valem em TODO projeto (escopo pessoal)

Agente e skill são descobertos por projeto: abrir a CLI em outro diretório não encontra nenhum dos 22 agentes nem a biblioteca de skills, e a conclusão natural de quem vê isso é que o framework não funciona. Instale no escopo pessoal uma vez:

izanagi export --cli claude --global   # ~/.claude/{agents,commands,skills}

Nunca escreve ~/CLAUDE.md: esse arquivo é a memória global de quem usa, e sobrescrevê-lo injetaria a descrição de um framework em todo repositório aberto. Agentes e skills são aditivos e ficam inertes até serem chamados.

O orquestrador escolhe o modelo de cada agente

O Commander é determinístico: classificar, decidir o modo, gerar contratos e estimar custo não gasta um token. O gasto acontece só nos nós, e cada nó recebe o modelo do PAPEL dele, com o agente tendo voz:

izanagi run agent-architect --task "desenhar um agente novo"

execute      agent-architect  commander   claude-opus-5     <- o agente declara `opus` no JSON dele
verify       qa               specialist  claude-sonnet-5   <- papel specialist: tier balanced
evaluation   -                worker      claude-haiku-4-5  <- tarefa pequena: tier fast

Precedência: --model / pin por papel (IZANAGI_MODEL_SPECIALIST, config roles) > tier declarado pelo agente > default do papel. O hint é um TIER, não um id: opus num catálogo sem premium cai para o melhor disponível, e o mesmo agente roda em Anthropic, OpenAI, modelo local ou CLI de agente sem mudar nada.

Política de tools do executor

O subprocesso roda sem nenhuma tool por padrão (--restricted --tools ""): nada de shell, nada de escrita, nenhum settings do projeto carregado. É o mais barato, o mais determinístico e o mais seguro.

izanagi run "..."                          # tools: none  (default)
izanagi run "..." --agent-tools read       # Read/Grep/Glob: o executor LÊ o repositório
izanagi run "..." --agent-tools write      # + Write/Edit: altera arquivos (opt-in explícito)

write é o único valor que autoriza alteração de arquivo, e Bash nunca entra em nenhuma das políticas.

Custo, medido

O CLI devolve o custo real de cada chamada (total_cost_usd), então neste executor o custo do run é medido, não estimado por tabela de preço. Números observados nesta máquina, num nó de specialist com chain de skills:

Política	Tokens do nó	Observação
none	~20.000 no modo direct, ~30.000 num nó de specialist	inclui o system prompt do CLI, cobrado em toda chamada
read	~68.000	várias voltas de tool e contexto do repositório multiplicam o consumo

Por isso --budget apertado estoura no primeiro nó, e por isso você não precisa passar --budget: quando o executor é o CLI de agente, o teto default do run sobe sozinho para o piso desta tabela. Piso recomendado: 65.000 por nó com none, 148.000 com read (a CLI avisa quando um --budget explícito fica abaixo disso).

O piso não é a média medida: é o topo da faixa observada, com folga de variância, dividido pela menor fatia que a fase execution recebe do teto (0,6). O erro aqui não é simétrico. Teto folgado não gasta um token a mais, porque o gasto é o que o nó consome e quem limita dinheiro é --max-cost, cobrado sobre custo MEDIDO; teto curto aborta o run depois de todo o custo já ter sido pago. Medido: com um piso dimensionado pela média, um run orchestrated produziu cinco artefatos válidos (7,4KB + 13,7KB + 23,7KB) e terminou sem gravar arquivo nenhum.

Teto não é gasto: num run orchestrated real o teto ficou em 260.000 e o consumo medido foi 147.140 (US$ 0,94). Para limitar dinheiro, use --max-cost.

Controles: IZANAGI_AGENT_CLI_DISABLED=1 desliga o executor · IZANAGI_AGENT_CLI_TIMEOUT_MS ajusta o timeout (default 300.000) · IZANAGI_AGENT_CLI_TOOLS=read|write é o equivalente de --agent-tools por ambiente. Dentro de um test runner o executor fica desligado por padrão, para que npm test nunca gaste cota real (IZANAGI_AGENT_CLI_IN_TESTS=1 libera).

Pesquisa aplicada: design, agentes e segundo cérebro

As referências encontradas nos posts salvos foram separadas entre inspiração e evidência. O framework absorve apenas padrões verificáveis:

• Design: Apple HIG e Playwright reforçam decisões centradas no usuário, contratos explícitos e teste do comportamento visível; isso alimenta anti-ai-slop, design-directions, motion-design e o QA visual.
• Processo: Spec Kit confirma o valor de separar constituição, especificação, plano, tarefas, implementação e convergência. O Izanagi já faz isso por contratos, grafo, verificação e journal; a especificação deve ser um artefato de entrada, não um prompt descartável.
• Segurança: Strix e o padrão “produzir → refutar → corrigir” inspiram uma etapa adversarial, mas qualquer ferramenta externa deve ser validada por fonte oficial antes de entrar no catálogo.
• Segundo cérebro: Markdown é a fonte canônica e Obsidian é uma interface humana opcional. Use raw/, wiki/, decisions/ e output/; não introduza banco vetorial até um benchmark provar ganho. O grafo visual ajuda navegação, não substitui MemoryStore, DecisionJournal ou EvidenceRegistry.

Fontes e classificação: references/instagram-ai-leads-2026.md.

Integridade das skills: o build valida que toda SKILL.md v2 tem alias no resolver e que toda skill declarada por um agent resolve para um arquivo real. No runtime, skills explícitas do nó são preservadas quando o ranking dinâmico adiciona contexto; cada tarefa recebe no máximo três skills ranqueadas. Em uma medição local de --prompt-only --compact, uma landing page gerou cerca de 13k tokens de prompt, antes do overhead do executor; use --compact para discovery e reserve read/write para nós que realmente precisam do projeto.

Quick Start

# 1. Inicializa um projeto com .agents/ e seleção interativa de packs de skills
izanagi init my-project
#    ou sem interação: izanagi init my-project --packs core,agents,coding,database

# 2. Executa uma tarefa. O modo é decidido pelo Commander, não fixo.
#    Sem API key: basta ter o Claude Code CLI instalado (izanagi doctor confirma).
izanagi run "Converta 10 dólares para reais"                  # modo direct: 1 chamada, sem grafo
izanagi run "Criar uma landing page de um SaaS de analytics"  # modo composto, com verificação
izanagi run "..." --mode autonomous --max-cost 0.50           # teto de custo respeitado no plano
izanagi run "adicionar paginação em GET /users" --output docs # lê o projeto e entrega o arquivo
izanagi run "..." --acceptance "o endpoint aceita ?page e ?limit"  # o que o usuário pediu, cobrado
izanagi run "..." --output src --verify-tests                # a métrica de teste vem do exit code do projeto
izanagi run "..." --min-quality 0.3                          # a estratégia mais barata que atinge o piso
izanagi run "..." --reuse-artifacts                          # segundo run da mesma pergunta não repaga a chamada
izanagi run "..." --agent-tools read                         # o executor lê o repositório antes de responder

# 3. Observabilidade, custo e auditoria
izanagi trace            # spans, healing, graph, avaliação
izanagi budget <run-id>  # para onde foi o orçamento: tokens por fase, custo, cache, degradação
izanagi models           # qual modelo cada papel receberia agora, e por quanto
izanagi explain <run-id> # por que o Izanagi decidiu o que decidiu
izanagi doctor           # integridade da instalação (--deep inclui security scan das skills)

Execução proporcional ao problema

O Commander classifica o objetivo (complexidade 1 a 5 + domínios) e escolhe um dos quatro modos. Antes, toda tarefa virava um grafo de 3 a 9 nós, inclusive "converta 10 dólares para reais".

Modo	Quando	Forma
direct	tarefa trivial de um domínio	1 chamada, sem grafo, sem crítica
assisted	tarefa simples	1 especialista + verificação determinística
orchestrated	problema composto	grafo com verificação, sem cauda opcional
autonomous	problema amplo (5/5 ou 3+ domínios)	grafo + healing + replan + verificação final

--mode força o modo. Sem override, um teto --max-cost faz o plano degradar de modo em vez de estourar o orçamento em silêncio.

Inteligência assimétrica

Cada tarefa recebe o modelo do seu papel, não o modelo do run: commander (tier premium) planeja e coordena, specialist (balanced) executa, worker (fast) faz extração, formatação e validação. Uma retentativa escala o papel em vez de repetir o modelo que já falhou. Fixe modelos por papel em .izanagi/izanagi.config.json:

{ "roles": { "commander": { "model": "claude-opus-4-1" },
             "specialist": { "model": "claude-sonnet-4-5" },
             "worker": { "model": "gemini-2.0-flash" } } }

Verificação por evidência

Nenhuma tarefa termina porque o agente disse que terminou. Cada contrato carrega critérios de aceite derivados do schema real do artefato e os que o usuário declarou (--acceptance), e a Verification Engine devolve VERIFIED, FAILED ou UNVERIFIED. Com --verify-tests, um dos critérios é o exit code do comando de teste do projeto: a única camada do runtime que decide por execução, e não por leitura de texto. Critério semântico é julgado por um modelo barato (papel worker, artefato resumido); com --no-judge, ou sem provider, ele nunca vira aprovação: fica UNVERIFIED, e o run reporta isso. Juiz que não conseguiu decidir também não reprova.

Com --prompt-only, apenas compila izanagi-prompt.md para colar manualmente em outra ferramenta, sem executar nada. Nós de aprovação (human-in-the-loop) pausam a execução até izanagi approve <run-id>.

O run lê o projeto e entrega arquivo

Dois nós do plano não chamam modelo nenhum: eles passam pela ToolRegistry, com permissão declarada no contrato, trust tier pela origem e política aplicada antes de executar.

Nó	Quando	Permissão	O que faz
survey	default num diretório com manifesto reconhecido; --no-survey desliga	fs:read	Levanta stack, manifestos, árvore por extensão, entrypoints e o começo do README. O resultado entra no contexto mínimo das tarefas raiz
materialize	--output <dir>, e só quando o plano produz artefato que pode carregar código	fs:write	Escreve os arquivos que o agente declarou (### FILE: <caminho> + bloco de código) em <output>/<slug>/
deliver	--output <dir>	fs:write	Grava o que o run produziu num documento único dentro do projeto

Nenhum nó de agente recebe permissão nenhuma: um agente não escreve, não lê arquivo e não executa comando. Há teste que percorre o plano inteiro conferindo isso nó a nó.

O survey existe porque a alternativa era pior e invisível: um agente escrevia sobre um projeto que nunca viu, inventava a stack e os caminhos, e o artefato passava na verificação — o schema pergunta se os campos existem, não se correspondem a alguma realidade. O levantamento é determinístico (não custa token), tem teto de profundidade e de entradas, e declara o próprio corte. Só as raízes do grafo dependem dele: repetir o mesmo levantamento em sete prompts seria a duplicação de contexto que a arquitetura proíbe.

A materialização tem uma fronteira que a torna defensável: os arquivos vão para um subdiretório da saída, nunca por cima do código do projeto. Aplicar sobre a fonte exigiria uma garantia que nenhuma verificação determinística consegue dar hoje; quem quer aplicar revisa e copia — e é aí que uma pessoa olha o diff. A escrita é tudo ou nada: a validação roda sobre o manifesto inteiro antes de qualquer arquivo tocar o disco, porque "6 arquivos escritos, 3 recusados" é o relatório que engana. Arquivo vazio, caminho absoluto, escape de diretório e marca de trabalho não feito (TODO, FIXME, implement later) recusam o manifesto inteiro.

A entrega muda o que a verificação significa. Um critério file-exists sobre um arquivo que ninguém escreveu passa quando o arquivo já existia por outro motivo; aqui o arquivo é gravado pela ToolRegistry e conferido depois, então o critério passa a significar "o runtime gravou isto". O nome do arquivo sai do objetivo, então repetir o mesmo objetivo reescreve a mesma entrega em vez de acumular um arquivo por execução — entrega é produto, e o histórico continua em .izanagi/state/.

SDK

import { izanagi } from 'izanagi-ai';

// Estimar antes de gastar: nenhum token é consumido aqui.
const plan = izanagi.plan({ objective: 'auditar a API de login' });
console.log(plan?.mode, plan?.estimate.maxCostUsd);

const run = izanagi.run({
  objective: 'auditar a API de login',
  budget: { maxCost: 0.5 },
  output: 'docs',   // grava a entrega em <baseDir>/docs; fora da raiz, run() rejeita antes de planejar
  // survey: false  // default: ligado quando baseDir tem manifesto reconhecido
});
run.on('task:start', (e) => console.log(e.data));
const result = await run;
console.log(result.status, result.telemetry?.estimatedCostUsd, result.verification);
console.log(result.deliveredTo);  // só presente quando a gravação REALMENTE aconteceu

Arquitetura Poliglota

O crescimento novo vive numa topologia poliglota que coexiste com o runtime npm legado em padrão Strangler Fig (ADR-001): contratos IPC, error codes e env vars canônicos em docs/POLYGLOT.md.

Componente	Linguagem	O que faz	Como testar
crates/izanagi_core	Rust	Quality engine: 7 heurísticas anti-slop sobre TS/Python/Go; protocolo NDJSON stdin/stdout (validate/rules/version) + op scan-rationalizations; bindings WASM feature-gated	cargo test --workspace (126 testes declarados no fonte)
crates/izanagi_mcp	Rust	Cliente MCP JSON-RPC 2.0 sobre stdio: discovery + invocação pontual (izanagi-mcp call --tool=<name>)	incluso no cargo test --workspace
go-services/swarm_orchestrator	Go	Orquestrador de swarm (Uber Fx): pipeline architect→engineer→qa→security via JSON-RPC 2.0 sobre UDS com event push	go build ./... && go vet ./... && go test ./...
python-engine/ast_analyzer	Python ≥ 3.10	Análise semântica multilíngue: símbolos, complexidade ciclomática, imports (tree-sitter + fallback estrutural)	.venv/bin/python -m pytest tests/ -q (41 testes)
packages/sdk (@izanagi/sdk)	TypeScript	Clientes tipados strict para os 4 núcleos + catálogo de skills; zero dependências de runtime	npm test dentro de packages/sdk (42 testes)
packages/cli (izanagi-next)	TypeScript	CLI de nova geração: run em 4 fases com auto-heal (N=2) + gate anti-racionalização; agent list, skill list/show --ref, gates check	npm test dentro de packages/cli (13 testes)

Diagnóstico rápido de todos os componentes:

izanagi polyglot status          # saúde dos núcleos poliglotas (--json | --strict)
node packages/agent-migrator/cli.mjs --check   # drift YAML ↔ JSON dos agentes
node packages/skill-migrator/cli.mjs --dry-run # valida migração skills v1 → v2 sem escrever

Estrutura do Repositório

izanagi-ai/
├── bin/                        Executável da CLI legado (bin/izanagi.js → dist/cli)
├── src/                        Runtime real em TypeScript (orchestrator, evaluation, resolver, scanner, factories, tools, tracer, llm, cli)
├── core/                       Engines (.md) + skill-resolver.json (aliases → targets + compositions)
├── agents/                     22 definições de agentes em JSON (fonte da verdade dos comandos)
├── skills/                     Skills legado v1 (skills/<name>/SKILL.md + references.md opcional)
├── .skills/                    Catálogo ativo v2 (.skills/<name>/SKILL.md + references/)
├── crates/                     Rust: izanagi_core (quality engine + WASM) e izanagi_mcp (cliente MCP stdio)
├── go-services/swarm_orchestrator/  Orquestrador de swarm em Go (Uber Fx, JSON-RPC 2.0 sobre UDS)
├── python-engine/              Analisador AST multilíngue (tree-sitter + fallback estrutural)
├── packages/                   sdk (@izanagi/sdk) · cli (izanagi-next) · agent-migrator · skill-migrator
├── references/                 Curadoria de referências reais por domínio (webgl-3d, scrollytelling, stack-2026...)
├── .agents/memoria/            Memória persistente anti-repetição (contexto, decisoes, erros-corrigidos, learnings)
├── .opencode/                  Comandos slash do Opencode (adapters em .claude/, .codex/, .cursor/...)
├── docs/POLYGLOT.md            Contratos IPC, error codes, env vars e resumo dos ADRs
├── AGENTS.md                   Instruções de operação do framework
├── ARCHITECTURE.md             Visão arquitetural
├── SYSTEM.md                   Fundação do sistema (arquitetura real do runtime)
└── RULES.md                    Regras operacionais (Anti-Generic High-Craft & Cinematic UI)

Comandos Principais da CLI

CLI legado (izanagi, publicada no npm):

Comando	Descrição
izanagi init [dir] [--packs a,b,c]	Cria projeto com .agents/ e seleção de packs de skills.
izanagi run [agent] --task "<task>"	Commander decide o modo, roteia por papel, executa o grafo, verifica contra os critérios de aceite e persiste trace + telemetria de custo. Flags: --mode direct|assisted|orchestrated|autonomous, --budget N, --max-cost N, --model <id>, --local (só providers locais, e serializa o pool: GPU única não ganha com paralelismo), --max-concurrency N (teto de tarefas em voo), --cache, --output <dir> (grava a entrega no projeto), --survey / --no-survey (força ou desliga o levantamento do projeto antes de decidir), --acceptance "<critério>" (repetível: o que a ENTREGA precisa cumprir, além do schema), --verify-tests (roda o comando de teste do projeto no fim do grafo e a métrica de teste passa a vir do exit code), --min-quality 0..1 (compara estratégias e escolhe a mais barata que atinge o piso de VERIFICAÇÃO), --reuse-artifacts (reaproveita artefato de run anterior com a mesma pergunta), --allow-tool <id> (allowlist de tools do run), --agent-tools none|read|write (política de tools do EXECUTOR de processo, diferente de --allow-tool: aqui se decide se o subprocesso do agente lê o repositório ou altera arquivos). Ctrl-C cancela o run em vez de matar o processo: o batch em voo é abortado, o progresso já gravado fica no checkpoint e izanagi resume <run-id> retoma dali, --no-commander (planejamento legado por categoria), --no-judge (desliga o juiz semantico), --prompt-only.
izanagi models [--json]	Catálogo de modelos, providers configurados e qual modelo cada papel (commander/specialist/worker) receberia agora, com custo por 10k tokens.
izanagi budget [run-id] [--json]	Para onde foi o orçamento daquele run: tokens por fase, custo estimado, cache local e do provider, contexto poupado, escaladas, degradação e verificação por tarefa.
izanagi chat	REPL interativo da CLI.
izanagi dashboard [--port N]	Dashboard local (Run Explorer, Arena, Memory).
izanagi agent create "<requisito>" [--name=slug] [--skills=a,b]	Agent Factory: gera agente com genome completo em agents/generated/ (detecta lacuna vs. 22 core).
izanagi agent list | inspect <name>	Lista/inspeta agentes (inclui agents/generated/) com genome.
izanagi skill create <nome> --gap="<descrição>" [--force]	Skill Factory: cria skill com frontmatter, security scan pré-escrita e recusa de lacuna já coberta.
izanagi skill list | search <q> | inspect <name>	Lista, busca e detalha skills (catálogo v2, com progressive disclosure).
izanagi create <agent|skill> <name>	Cria scaffold cru de agente (JSON) ou skill (SKILL.md), sem validação.
izanagi compile <agente> [arquivo]	Compila um System Prompt completo do agente + fundação do sistema.
izanagi workflow list | inspect <template>	Templates de grafo de execução por categoria (10).
izanagi eval <file.json> | --metrics ... | --report <run-id>	Evaluation Engine: métricas ponderadas + veredito (PASS/.../UNKNOWN).
izanagi benchmark [run|tokens|compare]	10 benchmarks builtin + comparação de regressões entre builds. tokens compara o plano do runtime legado com o do Commander (chamadas, tokens e custo, de forma determinística). Alias histórico: arena.
izanagi trace [run-id]	Traces de execução (spans, healing, graph, avaliação).
izanagi memory inspect | search <q>	Estado da memória de execução e busca em .agents/memoria/.
izanagi polyglot status [--json|--strict]	Saúde dos núcleos poliglotas (Rust, Go, Python, packages TS): checagens de existência + probes baratos; --strict sai com código 1 se algo estiver ausente.
izanagi doctor [--deep]	Auditoria de integridade; --deep adiciona security scan das skills.
izanagi diagnose	Diagnóstico profundo do runtime (state, agent genome, contratos de artifact).
izanagi resume <run-id>	Retoma execução interrompida (crash) ou pausada a partir do checkpoint: sem replanejar nem reexecutar nós concluídos.
izanagi approve <run-id> [node-id]	Aprova uma ação de alto risco pausada (nó kind: 'approval') e retoma.
izanagi reject <run-id> [node-id] [--reason]	Rejeita a ação pausada (o nó falha com o motivo) e retoma: self-healing/abort seguem normalmente.
izanagi explain <run-id>	Por que o Izanagi decidiu isso: decisões (Decision Journal) + conversa entre agentes + self-healing + veredito, sem chain-of-thought. --artifacts mostra o conteúdo produzido, --conversation o log A2A inteiro.
izanagi export --cli <cli>	Regenera adapters multi-CLI (opencode, claude, codex, cursor, copilot, kimi, all). Idempotente.
izanagi --version	Exibe a versão da CLI.

CLI de nova geração (izanagi-next, em packages/cli, requer Node ≥ 22): pipeline de agentes sobre os núcleos poliglotas, com gate anti-racionalização via Rust core e auto-heal (N=2 tentativas) no run em 4 fases.

cd packages/cli && npm install && npm run build
node dist/cli/src/index.js run --agent=architect --task="Design a caching layer"
node dist/cli/src/index.js agent list
node dist/cli/src/index.js skill list --category=rust   # ou --search=<termo>
node dist/cli/src/index.js skill show <nome> --ref=<arquivo>
node dist/cli/src/index.js gates check <file>

Skills & Agentes

23 agentes especializados (agents/*.json, fonte da verdade): /orchestrator, /discovery, /product-reasoner, /architect, /senior-engineer, /ai-engineer, /techlead, /automation-engineer, /security, /devops, /database, /qa, /bug-hunter, /docs, /pm, /professor, /researcher, /evaluator, /adversarial-critic, /form-engineer, /animation, /agent-architect, /skill-architect. Cada um carrega um Agent Genome de 13 campos e chains compostas; a tabela completa com papéis está em AGENTS.md.

Skills: 106 módulos legado v1 (skills/) e o catálogo ativo v2 (.skills/<name>/SKILL.md), ambos distribuídos no pacote npm. O formato v2 usa front-matter estruturado:

---

name: "anti-ai-slop"
description: "Detecta e corrige design 'cara de IA'..."
version: 2.0.0
category: design
tools:
  mcp:
    - mcp:fs_read
references:
  - "references.md"
---

Seguido de seções fixas: Triggering Criteria, Step-by-Step Workflow, Verification Steps, Common Rationalizations e Red Flags. O consumo é por progressive disclosure (izanagi skill inspect, ou izanagi-next skill show, carrega só o módulo necessário); skills nunca rodam isoladas — encadeiam via compositions do core/skill-resolver.json (258 aliases, 16 composições).

Desenvolvimento

Ordem importa: dist/ é gitignored e bin/izanagi.js importa de ../dist/cli/index.js — rode npm run build antes de qualquer comando CLI local (doctor, polyglot status, export...), senão roda código obsoleto ou quebra. O mesmo vale para packages/*/dist.

# Legado npm (raiz)
npm install
npm run build       # tsc && node dist/scripts/generate-manifest.js
npm test            # build + node --test dist/runtime/tests/*.test.js (966 testes)
npm run verify      # build + teste de instalação em sandbox (passa todos os pack IDs)
npm run doctor      # node bin/izanagi.js doctor [--deep]

# Núcleos poliglotas
cargo test --workspace                                        # Rust: core + mcp (126 testes declarados no fonte)
cargo check -p izanagi_core --features wasm                   # type-check dos bindings WASM
(cd go-services/swarm_orchestrator && go build ./... && go vet ./... && go test ./...)
(cd python-engine && python -m venv .venv && .venv/bin/python -m pip install -r requirements-dev.txt)  # o venv NAO e versionado
(cd python-engine && .venv/bin/python -m pytest tests/ -q)     # 41 testes
(cd packages/sdk && npm install && npm test)                  # 42 testes
(cd packages/cli && npm install && npm test)                  # 13 testes

Requisitos por componente: Node ≥ 18 (raiz) e ≥ 22 nos pacotes novos, Rust stable, Go 1.26, Python ≥ 3.10.

Publicando no NPM

CD exclusivo de tag v* (.github/workflows/publish.yml): bump → commit → tag → push; o workflow publica com provenance OIDC (SLSA v1). Localmente, o fluxo manual permanece:

npm run bump:patch   # ou bump:minor / bump:major
npm publish          # prepublishOnly roda o build automaticamente

CI (.github/workflows/polyglot.yml): 6 jobs paralelos em push/PR para main — legacy-npm, rust (clippy+test+wasm check), wasm-build E2E, go, python, ts-packages.

Trabalho agendado (sem servidor)

O Izanagi é local-first por decisão: não existe daemon, porta escutando nem credencial em repouso. Quem agenda é o cron ou o Task Scheduler do sistema.

izanagi run "auditar dependências e abrir relatório" --json --notify-webhook=https://exemplo/hook

--json	Um único objeto JSON no stdout. A saída humana é silenciada; console.error continua vivo, porque erro real precisa chegar ao stderr do agendador.
código de saída	0 concluiu · 1 falhou · 2 aguarda decisão humana. Aguardar aprovação não é falha e não deve alertar como falha.
--notify-webhook=<url>	POST de fim de run, uma retentativa. 4xx não é repetido (configuração errada não melhora repetindo), 5xx é. Falha de notificação nunca derruba o run.

O webhook leva metadado: status, score, tokens, custo, verificação por tarefa e nomes de artefato. Nunca o conteúdo produzido — um endpoint de notificação costuma ser um canal de equipe ou um serviço que ninguém auditou. Para o conteúdo, izanagi explain <run-id> --artifacts, na máquina onde o run aconteceu.

Documentação

Documento	Conteúdo
AGENTS.md	Reference operacional: os 23 agentes, comandos, gotchas de desenvolvimento e release flow.
docs/POLYGLOT.md	Contratos IPC entre núcleos, error codes JSON-RPC, tabela de env vars, gaps conhecidos e resumo dos ADRs.
docs/HANDOFF.md	Passagem completa da rearquitetura v3.13.0 → v3.18.0: o que mudou, onde cada coisa vive, decisões e por quê, bugs encontrados, números medidos e por onde continuar. Comece por aqui se pegou o repositório sem contexto.
docs/RUNTIME-PENDING.md	Nenhum item aberto: a tabela do que foi fechado, em qual commit e como, mais as limitações que são escolha com motivo registrado.
ARCHITECTURE.md	Visão arquitetural do framework e da topologia poliglota.
CONTRIBUTING.md	Guia de contribuição: convenções, fluxo de PR e padrões do repo.
ROADMAP.md	Planejamento de evolução por waves e marcos.
SYSTEM.md / RULES.md	Fundação do runtime e regras operacionais (Anti-Generic High-Craft & Cinematic UI).
CHANGELOG.md	Histórico de versões.

Licença

MIT: Use, modifique, distribua. Apenas mantenha os créditos.