Factory Agent

Fábrica de software multiagente orientada por especificações, evidências e aprovação humana.

O Factory Agent conduz uma ideia por descoberta, requisitos, arquitetura, planejamento, desenvolvimento, revisão, QA, aceite e documentação. As mesmas regras cobrem suporte, triagem e correção de bugs, além da reconstrução rastreável de sistemas documentados pelo Reversa.

A CLI administra instalação, estado, integridade e retomada. A inteligência especializada fica em skills Markdown portáveis, executadas por Claude Code, Codex ou Pi Agent. Para operação totalmente local, o runtime direto integra modelos do Ollama sem solicitar ou armazenar chaves de LLM.

Por que usar

• Estado físico verificável: o próximo agente é derivado dos artefatos existentes, não apenas de uma flag.
• Gates humanos: propostas críticas só são aplicadas após aprovação explícita.
• Instalação não destrutiva: arquivos existentes e customizações locais são preservados.
• Agentes especializados: cada etapa possui entradas, saídas e áreas de escrita definidas.
• Portabilidade: o mesmo projeto pode usar Claude Code, Codex, Pi Agent e Ollama.
• Engenharia reversa com curadoria: documentação legada vira insumo rastreável, nunca requisito automático.

Requisitos

• Node.js 20 ou superior;
• Claude Code, Codex ou Pi Agent para executar as skills; ou
• Ollama opcional para o runtime local direto.

O Factory Agent não instala engines, Ollama ou modelos automaticamente.

Instalação

Sem instalação global:

npx @sidnei_ali/factory-agent factory --help
npx @sidnei_ali/factory-agent install --engines=pi-agent --project=MeuProjeto

Como comando global:

npm install --global @sidnei_ali/factory-agent
factory --version

Para desenvolver a partir do repositório:

git clone https://github.com/sidneiali/factory-agent.git
cd factory-agent
npm test
node bin/factory.js --help

Ativacao opcional no Pi

A instalacao do engine pi-agent instala somente as skills; a extensao nao e carregada automaticamente em projetos em manutencao. Para iniciar o Pi com o Factory Agent habilitado:

factory pi
# ou
npx @sidnei_ali/factory-agent factory pi

Tambem e possivel usar o pacote diretamente no Pi:

pi -e npm:@sidnei_ali/factory-agent

Para manter o Pi sem extensoes na sessao atual, use pi --no-extensions.

Início rápido

Com Claude Code, Codex ou Pi Agent

Instale os adaptadores e as skills no projeto alvo:

factory install \
  --root=/caminho/do/projeto \
  --engines=claude-code,codex,pi-agent \
  --project=MeuProjeto

Inicie o workflow pela engine escolhida:

| Engine | Comando inicial | |---|---| | Claude Code | /factory-new | | Codex | factory-new | | Pi Agent | factory pi, depois /factory-new |

Depois, acompanhe o estado físico:

factory status --root=/caminho/do/projeto
factory doctor --root=/caminho/do/projeto

Com Ollama local

Com o servidor Ollama já instalado e iniciado:

factory install --engines=pi-agent --project=MeuProjeto
factory provider models ollama
factory provider select ollama --model=nome-do-modelo --timeout=120000
factory provider test ollama
factory new "Criar uma aplicação para controlar tarefas"
factory run
factory approve
factory resume

factory run cria uma proposta. factory approve aplica somente artefatos novos; factory reject <motivo> rejeita a proposta sem aplicá-la.

Workflow principal

discovery
  → requirements
  → architecture
  → plan
  → developer
  → reviewer
  → qa
  → acceptance
  → documentation

Fluxos de manutenção:

• factory-support: intake e classificação;
• factory-bug: triagem e reprodução, sem correção;
• factory-bug-fix: causa raiz, plano aprovado e prova vermelho → verde.

Engines e runtime

| Integração | Como funciona | Entrada principal | |---|---|---| | Claude Code | Skills e comandos Markdown instalados no projeto | /factory-new | | Codex | Skills universais e comandos compatíveis | factory-new | | Pi Agent | Skills universais, extensão local, ferramentas e TUI | /factory-new | | Ollama | Provider local usado pelo runtime direto e pelo Pi | factory run |

A instalação do Pi usa exclusivamente as skills universais em .agents/skills/, evitando cópias concorrentes. A extensão é opt-in: use factory pi, npx @sidnei_ali/factory-agent factory pi ou pi -e npm:@sidnei_ali/factory-agent. Ela registra comandos /factory-*, ferramentas de estado e decisão, e modelos de chat Ollama disponíveis no ambiente.

O endpoint padrão do Ollama é http://127.0.0.1:11434. Para alterá-lo:

factory provider select ollama \
  --base-url=http://127.0.0.1:11434 \
  --model=meu-modelo \
  --timeout=120000

Reversa Bridge

O Reversa Bridge transforma uma saída de engenharia reversa em insumo controlado para um sistema novo. O Reversa permanece externo: o Factory Agent não o instala, não o executa e nunca modifica o legado.

factory install --root=/novo-sistema --engines=pi-agent --project=NovoSistema
factory import reversa --source=/sistema-legado --root=/novo-sistema
factory new --from-reversa --root=/novo-sistema
factory status --root=/novo-sistema

Durante a importação, o Factory Agent:

1. valida os artefatos obrigatórios do Reversa;
2. cria um snapshot imutável com hashes SHA-256;
3. preserva evidências, confiança, gaps e identificadores REV-*;
4. mantém origem legada e sistema-alvo em árvores separadas;
5. exige uma decisão para cada regra importada:
   • PRESERVE;
   • MODERNIZE;
   • DISCARD;
   • HUMAN_DECISION;
   • GAP;
6. mantém rastreabilidade até requisito-alvo, ADR, ação, código, teste e evidência de paridade.

Detalhes em Reversa Bridge.

Comandos principais

| Comando | Função | |---|---| | factory install | Instala estado, políticas, adaptadores e skills | | factory status | Detecta o estágio físico e o próximo agente | | factory doctor | Verifica estado, manifesto, engines e arquivos | | factory update | Atualiza intactos, restaura ausentes e preserva customizações | | factory add-agent <id> | Adiciona ou restaura uma skill conhecida | | factory add-engine <id> | Adiciona Claude Code, Codex ou Pi Agent | | factory pi | Inicia o Pi com o Factory habilitado somente na sessão atual | | factory provider ... | Lista, seleciona e testa providers e modelos | | factory new "ideia" | Inicia um workflow direto | | factory run [agente] | Executa o próximo agente pelo provider ativo | | factory approve | Aprova e aplica artefatos novos da proposta | | factory reject <motivo> | Rejeita a proposta pendente | | factory resume | Reconcilia runtime e artefatos físicos | | factory import reversa --source=<legado> | Importa um snapshot Reversa | | factory new --from-reversa | Inicia reconstrução pelo snapshot ativo | | factory uninstall | Remove somente arquivos intactos criados pela ferramenta |

Consulte a referência completa da CLI.

Estrutura instalada no projeto

.factory/              estado, providers, propostas, políticas, eventos e manifesto
.pi/extensions/        extensão local do Pi Agent
.agents/skills/        skills universais compartilhadas pelas engines
_factory_product/      brief, requisitos, arquitetura, ADRs e imports Reversa
_factory_delivery/     planos, ações, revisão, QA, aceite e documentação
_factory_operations/   suporte, bugs e evidências operacionais

Segurança e limites

• instalação não sobrescreve arquivos de entrada existentes;
• atualizações usam SHA-256 e preservam customizações;
• desinstalação preserva arquivos modificados;
• exclusão, deploy, publicação, dependências e migrações exigem aprovação;
• legado e snapshots importados são tratados como somente leitura;
• o runtime direto não sobrescreve arquivos existentes;
• a extensão Pi intercepta ferramentas conhecidas, mas não constitui um sandbox do sistema operacional;
• nenhuma migração real, operação destrutiva ou instalação de modelo é executada automaticamente.

Leia a política de segurança antes de usar o projeto em ambientes sensíveis.

Documentação

• Visão geral
• Instalação
• Guia de uso
• Referência da CLI
• Configuração
• Engines e providers
• Workflow
• Agentes
• Reversa Bridge
• Segurança
• Solução de problemas

Se MkDocs estiver disponível:

mkdocs serve

Desenvolvimento

npm test
npm run check
npm pack --dry-run

Os contratos de produto e arquitetura ficam em docs/product/.

Origem conceitual

O projeto foi inspirado por padrões observados no sandeco/reversa, especialmente skills portáveis, artefatos operacionais, retomada por estado físico e gates humanos. A implementação do Factory Agent é independente e voltada à criação e reconstrução segura de aplicações.

Licença

MIT. Consulte LICENSE.