Criei um pacote para trabalhar com duas IAs, melhorar planos e economizar tokens · willdeschepper

Se você usa agentes de IA pra codar, já passou por isso: gera um plano com uma IA, copia e cola pra outra validar, volta pra primeira executar. Você vira o middleware humano entre ferramentas que deveriam conversar sozinhas.

O MuAiFlow nasceu dessa frustração. É um framework de workflow baseado em arquivos Markdown que qualquer IA consegue ler e seguir — sem copiar e colar contexto entre ferramentas.

A ideia central

[IA #1] Gera o plano     →  DRAFT
[IA #2] Revisa o plano   →  AI_REVIEWED
[HUMANO] Aprova          →  HUMAN_APPROVED  ← só humano faz isso
[IA] Executa             →  EXECUTING → DONE

Uma IA planeja, outra diferente revisa, e nenhuma IA pode aprovar — só você. Essa é a regra de ouro: HUMAN_APPROVED só pode ser setado por humano.

Planos ficam melhores quando uma segunda IA questiona antes de escrever código. Riscos arquiteturais aparecem. Edge cases surgem. E você mantém o controle.

Por que não só usar uma IA?

Porque cada ferramenta tem suas forças e limitações. Codex CLI tem limite generoso de tokens mas pode perder nuances. Claude tem raciocínio forte mas tokens acabam rápido. Crush é versátil.

O MuAiFlow deixa você ser estratégico:

Fase	Melhor ferramenta	Por quê
Planejar	A que tem mais tokens (ex: Codex)	Planejamento consome muitos tokens
Revisar	A mais forte em raciocínio (ex: Claude)	Revisão é curta mas de alto valor
Executar	A que tem mais tokens (ex: Codex)	Execução é a fase mais pesada

O workflow não muda independente das ferramentas que você usa. O arquivo .ai/plans/ é o contrato — qualquer IA que lê arquivos participa.

Como funciona na prática

1. Instala

pnpm add -D muaiflow

Isso copia a pasta .ai/ pro seu projeto automaticamente com templates, prompts e scripts.

2. Cria um plano

npx muaiflow plan minha-feature --tracked
# cria → .ai/plans/tracked/2025-07-15-minha-feature.md

Quer um plano privado que não entra no Git? Usa --local:

npx muaiflow plan minha-feature --local
# cria → .ai/plans/local/2025-07-15-minha-feature.md

3. Pede pra IA preencher

codex "Siga .ai/prompts/plan-generation.prompt.md para preencher .ai/plans/tracked/2025-07-15-minha-feature.md com um plano para [descrever tarefa]"

4. Outra IA revisa

"Siga .ai/prompts/multi-ai-review.prompt.md para validar .ai/plans/tracked/2025-07-15-minha-feature.md"

A IA revisora verifica cada arquivo citado, aponta riscos com arquivo:linha, e separa blockers de sugestões.

5. Você aprova

Abre o arquivo do plano e preenche:

status: HUMAN_APPROVED
human_approved_by: seu-nome

6. IA executa

codex "Siga .ai/prompts/execute-approved-plan.prompt.md para executar .ai/plans/tracked/2025-07-15-minha-feature.md"

O que vem no pacote

Templates de plano com frontmatter YAML estruturado (status, autor, revisor, aprovação)
Prompts prontos para cada fase: gerar plano, revisar, executar, handoff, code review
CLI para criar planos e gerenciar contexto sem esforço
Script de handoff para trocar de IA no meio da tarefa sem perder contexto
Skills instaláveis via skills.sh para agentes que suportam
Extensão VS Code para referenciar arquivos do projeto dentro de planos Markdown com @

Planos tracked vs local

.ai/plans/
├── tracked/    ← entra no Git, compartilhável com o time
├── local/      ← ignorado pelo Git, rascunhos privados
├── TEMPLATE.md
└── context.md  ← dados de referência para o plano atual

--tracked é o padrão. Use --local para experimentos que não precisam de histórico.

Contexto grande? Sem problema

Precisa passar schema do banco, exemplos de API, regras de negócio? Coloca em .ai/plans/context.md:

npx muaiflow context         # cria do template se não existe
npx muaiflow context --reset # reseta do template
npx muaiflow context --clear # limpa o conteúdo

A IA lê automaticamente quando gera o plano.

Trocando de IA no meio (handoff)

Acabou o token de uma IA? Quer trocar pra outra?

bash .ai/scripts/handoff.sh codex

O script gera um snapshot com branch, status do Git, plano atual e progresso. A próxima IA continua de onde parou.

Smart Model Routing

Nem toda tarefa precisa do modelo mais caro. Cada task no plano pode ter um tier:

Tier	Quando usar	Exemplo
`reasoning`	Arquitetura, segurança, debug complexo	Projetar fluxo de auth
`standard`	Lógica de negócio, endpoints	Implementar CRUD
`fast`	Boilerplate, testes, docs	Gerar arquivo de i18n

Resumindo

O MuAiFlow resolve um problema simples: você não deveria ser o middleware entre IAs. Em vez disso:

Cada IA tem um papel claro (planejar, revisar, executar)
O plano é um arquivo Markdown que qualquer IA lê
Nenhuma IA executa sem sua aprovação
Você escolhe qual ferramenta usar em cada fase
O contexto sobrevive troca de ferramenta

É open source, MIT, zero dependências runtime, e funciona com qualquer IA que lê arquivos.

pnpm add -D muaiflow

GitHub: github.com/4rweb/MuAiFlow