# File Queue Orchestration

> Padrão para rodar tarefas de IA em fila baseada em arquivos, com isolamento em sandbox, versionamento em git e revisão humana obrigatória antes de aplicar. Use ao construir automação que deixa um modelo escrever ou alterar arquivos sem supervisão em tempo real.

- Skill: `slayer1dev/file-queue-orchestration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add slayer1dev/file-queue-orchestration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/slayer1dev/file-queue-orchestration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Slayer1Dev (https://skillmd.com/u/slayer1dev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/slayer1dev/file-queue-orchestration

---


# Fila de tarefas com gate de revisão

Para automação onde um modelo produz alterações sem alguém olhando em tempo real. O problema não é o modelo errar — é o erro chegar em produção sem ninguém ver.

## Por que arquivo, e não fila de verdade

Redis ou SQS são melhores em throughput. Mas para orquestrar IA, fila em arquivo ganha em:

- **Inspecionável** — `cat` no job mostra o estado. Debug sem ferramenta.
- **Durável de graça** — sobrevive a reboot sem configuração.
- **Versionável** — o diretório inteiro entra no git.
- **Sem dependência** — nada para instalar, subir ou monitorar.

Throughput raramente é o gargalo: o modelo leva segundos ou minutos por tarefa. Se você precisa de milhares por segundo, este padrão não é o seu.

## Estrutura

```
fila/
  in/<id>.json       tarefa a executar
  out/<id>.json      resultado + status
  logs/
sandbox/
  jobs/<id>/
    input/           cópia intocada — referência para o diff
    work/            onde o worker escreve
    TASK.md          prompt e contexto
    DIFF.patch       gerado ao final
```

A separação `input/` e `work/` é o núcleo: sem cópia original, não há diff confiável, e sem diff não há revisão possível.

## Ciclo

1. Tarefa aparece em `in/`
2. Cria diretório do job; copia os arquivos alvo para `input/` **e** `work/`
3. Escreve `TASK.md` com prompt e contexto
4. Roda o worker com `cwd` no diretório do job
5. Commita o resultado e gera `DIFF.patch` entre `input/` e `work/`
6. Grava `out/<id>.json` com status **`needs_review`**
7. **Para.** Humano lê o diff e decide aplicar

O passo 7 é o ponto do padrão. Sem ele, é só automação com etapas extras.

## Isolamento

O worker roda preso ao diretório do job:

- `cwd` no diretório do job, nunca na raiz do projeto
- Sem permissão ampla — nada de pular todos os prompts de permissão
- Regras de negação para caminhos sensíveis
- Timeout obrigatório: worker travado consome recurso indefinidamente

Assuma que o worker vai tentar sair da caixa por engano — ler um caminho absoluto, escrever fora do escopo. Estruture para que a tentativa falhe em vez de depender de ele não tentar.

## Troca de motor

Parametrize qual modelo executa o job em vez de fixar no código:

```json
{ "prompt": "...", "engine": "a", "model": "...", "timeout": 180000 }
```

Ganhos: comparar motores na mesma tarefa, cair para outro quando um esgota a cota, e usar o barato no mecânico. O custo é uma camada fina de tradução de argumentos — cada CLI tem a sua sintaxe de modo não-interativo.

## Erros que este padrão previne

| Erro | Como o padrão evita |
|---|---|
| Modelo sobrescreve arquivo bom | Produção nunca é o diretório de trabalho |
| Mudança ruim descoberta tarde | Diff revisado antes de aplicar |
| "O que exatamente mudou?" | Commit por job |
| Job trava e consome recurso | Timeout obrigatório |
| Worker vaza para fora do escopo | Sandbox com cwd restrito |

## Quando não usar

- Tarefa precisa de resposta imediata — revisão adiciona latência humana
- Volume alto o bastante para a revisão virar gargalo
- Operação puramente de leitura, sem efeito colateral