gremlins

# Gremlins Gremlins é uma ferramenta CLI em Rust que inicia agentes de codificação em segundo plano (chamados "gremlins") para executar autonomamente o ciclo completo de desenvolvimento de software: plan → implement → review-code → address-code. Dada uma meta ou uma issue do GitHub, um gremlin é executado de ponta a ponta sem supervisão, gravando artefatos em um diretório de estado por usuário e, opcionalmente, abrindo um pull request. Um gerenciador de frota rastreia gremlins em execução, travados e finalizados, oferecendo operações como stop, land e close. **Status:** Totalmente novo e em desenvolvimento ativo. Espere arestas ásperas, timeouts de stream e conflitos de merge ocasionais de gremlins paralelos. ## Principais Recursos - **Pipeline autônomo:** Executa as etapas de planejamento, implementação, revisão e correção de código sem intervenção humana. - **Gerenciamento de frota:** Rastreie, pare, integre, feche e limpe gremlins via subcomandos da CLI. - **Suporte a múltiplos repositórios:** Inicie gremlins de repositórios diferentes; o estado é isolado por gremlin. - **Sistema de fila:** Adicione, liste, execute, reenfileire e limpe inicializações de gremlins na fila. - **Execução paralela:** Execute múltiplas revisões ou outras etapas simultaneamente com semântica fan-out/fan-in. - **Vinculação de artefatos:** Passe dados entre etapas via URIs (file, git, opaque) e interpolação. - **Definições personalizáveis:** Definições de etapas baseadas em YAML com padrões reutilizáveis, prompts e substituições de cliente. - **Integração com GitHub:** Abra PRs, solicite revisões do Copilot, aguarde verificações de CI e faça merge via CLI `gh`. ## Subcomandos da CLI - `launch <name>` — Inicia um gremlin em segundo plano pelo nome da definição. - `resume` — Regera um gremlin existente a partir de sua etapa registrada. - `stop` — Envia SIGTERM para um gremlin em execução. - `land` — Integra um gremlin finalizado ao branch atual. - `rm` — Exclui o diretório de estado e o worktree de um gremlin. - `close` — Marca um gremlin como fechado. - `log` — Acompanha o arquivo de log do gremlin. - `ack` / `skip` — Confirma ou ignora um gremlin aguardando entrada humana. - `queue` — Gerencia a fila de inicialização (add, list, run, requeue, clear, set-state, stop). - `prompt-for-assistant` — Imprime o prompt de configuração do assistente. - `artifacts` — Inspeciona chaves e vinculações de artefatos. - `clean` — Limpa diretórios de estado de gremlins finalizados. ## Configuração Gremlins usa definições YAML com etapas. Os principais elementos de configuração incluem: - **`default_client`:** String obrigatória `provider:model` (por exemplo, `xai:grok-4`). - **`base_ref`:** Ref Git a partir da qual os worktrees são ramificados (padrão `current`). - **`github_integration`:** Habilita a integração com a CLI `gh`. - **`bootstrap`:** Flags de origem da CLI, comandos de inicialização, comandos por worktree e vinculações de artefatos. - **`prompts` / `prompt_dir`:** Mapa nomeado de prompts e diretório para resolução de prompts. - **`stage-definitions`:** Padrões de etapas nomeados e reutilizáveis. - **`land`:** Etapa exec personalizada para integração (por exemplo, `gh pr merge`). - **`stages`:** Lista ordenada de etapas ou grupos paralelos. ### Tipos de Etapa **Primitivas:** `agent`, `exec`, `loop`, `parallel`, `sequence`. **Receitas:** Etapas YAML predefinidas como `plan`, `plan-gh`, `implement`, `verify`, `github-open-pr`, `github-push-to-pr-branch`, `github-request-copilot-review`, `github-wait-copilot`, `github-wait-ci`. ### Grupos Paralelos Execute etapas irmãs simultaneamente com `type: parallel` e uma lista `body:`. Suporta `max_concurrent`, `cancel_on_error` e `error_policy` (any/all). ### Vinculação de Artefatos As etapas podem vincular e interpolar artefatos via URIs: - `file://session/<name>` — Arquivo de artefato da sessão. - `git://ref/<name>` — Nome da ref Git. - `git://commit/<sha>` — SHA do commit. - `git://range/<base>..<head>` — Intervalo/log de commits. - `opaque://pr/<n>` — Identificador opaco de PR. ## Instalação Requer `gh` (GitHub CLI) e `git`. Compile com `cargo build`. Os alvos make incluem `test`, `rust-test`, `rust-fmt`, `rust-fmt-check`, `rust-clippy` e `check`. ## Exemplo ```sh gremlins launch local # local.yaml incluído gremlins launch gh # gh.yaml incluído gremlins launch gh --plan '#42' --wait ``` Definições locais do projeto podem substituir as incluídas via `.gremlins/<name>.yaml`. ## Casos de Uso - Automatizar alterações rotineiras de código a partir de issues do GitHub. - Executar revisões de código paralelas com modelos ou focos diferentes. - Gerenciar múltiplos agentes de codificação autônomos em repositórios. - Integrar com CI/CD e fluxos de trabalho do GitHub (criação de PR, revisões do Copilot, verificações de CI).