flowral.docs
Início/Colaboração

Flowral Linux — instruções para code agents

Contrato do projeto. Para tarefas especializadas, veja workforce. Documentação existente não significa software implementado.

1. Fontes de verdade e decisões

  • Antes de editar: ler somente README.md, decisões, arquitetura, a especificação do domínio afetado e seus testes. Expandir contexto só diante de uma hipótese concreta.
  • Tratar aprovado, proposto, aberto, planejado e implementado como estados diferentes. Nenhum agente aprova alterações de stack ou scope por conta própria.
  • Preservar trabalho de usuários e de outros agentes. Inspecionar git status antes de operações Git quando houver checkout. Não presumir que rollback, branch limpa ou backup existem.
  • Preferir reutilizar → refatorar o trecho necessário → mover → reescrever como último recurso. Alterações incrementais, com testes e reversibilidade.
  • Distinguir pass, fail, not run, blocked nos relatórios; jamais atribuir verificação a comando não executado ou a screenshot não inspecionada.

2. Contratos arquiteturais inegociáveis

  • Base: Void Linux x86_64 glibc, runit, XBPS; não assumir systemd, apt, pacman ou service manager alternativo.
  • Desktop: Swirl/Wayland, scrolling tiling e floating; manter compositor e protocolos existentes. Não implementar compositor do zero.
  • Aplicativos próprios: Rust + Slint. Separar crates de domínio/configuração, serviços/adaptadores, modelos de UI e visualizações; Slint não contém regras de autenticação, pacotes ou rede.
  • Apresentação consulta estado e solicita comandos tipados e validados. Cada comando público relevante documenta entradas, saídas, falhas, permissões e rollback; jamais expor shell arbitrário pela GUI.
  • Preferir dados serializáveis explícitos, struct/enum, funções pequenas e composição. Evitar frameworks abstratos e hierarquias especulativas; não proibir traits/abstrações idiomáticas quando necessárias.
  • Nomes descritivos em inglês para código: availableMemoryBytes (Rust: available_memory_bytes), não mem, ctx, mgr e parâmetros de uma letra sem motivo. Respeitar nomes de protocolos/FFI apenas nas bordas externas.
  • Dependências de domínio não apontam para Slint, IPC, D-Bus, file picker ou implementações específicas. Nenhum ciclo de dependência. Bibliotecas adicionais exigem motivo concreto, custo e licença.
  • Validar JSON/TOML, URLs, comandos, paths, symlinks, configs, providers, MCPs e entradas externas em sua fronteira. Type assertions ou desserialização parcial não equivalem a validação.
  • Rust seguro por padrão; unsafe só em módulo auditável de FFI/sistema com invariantes documentadas. Evitar unwrap/expect em caminhos que processam falhas externas. Erros explícitos e mensagens compreensíveis.
  • Possuir explicitamente recursos de Wayland/GPU, handles e subprocessos: liberar uma vez, encerrar processos próprios e não descartar objetos compartilhados por instância.

3. Produto e experiência

  • Visual Flower Paper: Sakura, Daisy, Petunia × Light/Dark, tema consistente em Flowral UI, WezTerm, Fish, Neovim e integrações realmente suportadas.
  • Sem titlebar/botões desenhados pelo compositor; CSD de terceiros pode escapar ao controle global. Não prometer que será possível removê-las de qualquer app.
  • Acessibilidade prioritária: teclado integral, foco visível, contraste, legibilidade, reduced motion, feedback não apenas por cor, sem captura involuntária de foco.
  • Flowral DE substitui interfaces em fases; Swirl, NetworkManager, BlueZ, PipeWire, greetd, swaylock, swayidle, polkit e portais permanecem como mecanismos consolidados até decisão explícita e testes.
  • Flowral Files e Flowral Terminal são somente ideias futuras, não escopo ativo. WezTerm e PCManFM continuam aprovados.
  • Medir desempenho real com protocolo. Meta experimental: até 300 MiB no desktop idle do ThinkPad Edge E430; nunca alegar atingida sem medição repetível.

4. Segurança de host, VM e desktop

  • Não instalar em disco físico, modificar partições/bootloader, apagar arquivos desconhecidos, rodar sudo/root, fazer git push ou publicar release sem autorização no escopo da tarefa.
  • Antes de operações grandes: checar espaço disponível, caminhos de saída e o alvo. Testes de ISO somente em VM/disco descartável; snapshot/backup não substitui inspeção.
  • Interfaces GUI sem root. Operações privilegiadas via helper estreito e polkit; jamais passar shell arbitrário a esse helper.
  • Não gravar/ecoar tokens de IA, SSID, MAC, serial, env brutos e credenciais em configs, logs, screenshot ou artifacts. MCPs são código externo: comando/origem/escopo requerem consentimento.
  • Slint MCP e serviços de debug somente em loopback/VM de desenvolvimento, nunca na imagem de release. Não desabilitar sandbox ou proteção de GPU para “fazer passar”.
  • Nunca usar perfil pessoal de navegador em automação; usar perfil dedicado, não mover ponteiro da sessão pessoal nem tomar foco sem necessidade. Processos encerrados devem ser somente os iniciados pela automação.
  • Operações pesadas escalonadas: inicialmente até 2 workers de teste e 1 visual, sem múltiplos builds/VMs pesados concorrentes. Limitar timeouts, tamanho de downloads e uso do disco.

5. Verificação em camadas

  • Documentação/site: validar links, gerador Python do site e GitHub Pages conforme pipeline existente.
  • Rust (quando existir Cargo workspace): cargo fmt --check, cargo clippy --workspace --all-targets, cargo test --workspace; registrar se impossíveis.
  • Slint: preview/MCP e screenshot real, verificar Light/Dark, foco, teclado, teclado reduzido, erro e 1366×768. Mocks não provam visual final.
  • Wayland/Swirl: verificar IPC, layer-shell/foco, resizing, múltiplos outputs e encerramento em compositor nested quando suportado; senão VM.
  • Sistema: testes de serviço e boot na VM Void, BIOS/UEFI e fallback TTY; no Edge E430 só sob autorização explícita.
  • Segurança/IA: casos inválidos, negação de permissão, rollback, falha de servidor, cancelamento, processos órfãos e segredos; reviewers independentes para mudanças críticas.
  • Capturas comparáveis devem fixar tema, viewport, escala, fontes, estado e dados de teste. Não “aprovar” ausência de imagem/Wayland marcando teste como pass; usar blocked.

6. Trabalho em etapas, skills e agentes

  1. Definir escopo, exclusões e aceite; inspecionar estado e evidências de baseline.
  2. Escolher somente skills pertinentes sob .opencode/skills/ e perfil, se necessário, sob .opencode/agents/; não carregar todo o catálogo do Prumo.
  3. Adicionar teste de regressão antes ou junto da implementação menor possível.
  4. Executar gates relevantes e verificar diffs por mudanças não relacionadas, dependências novas, privacidade e segurança.
  5. Para implementação, passar resultado a reviewer distinto quando possível; reviewer não modifica o código que audita.
  6. Atualizar specs, decisões e roadmap afetados; documentação canônica do Flowral permanece em pt-BR. Traduzir para outros idiomas apenas com decisão de localização do projeto.
  7. Handoff: resultado, paths, revisão/commit, testes com pass/fail/not run/blocked, prints/VM/host usados, limites, risco, rollback e próximo passo.

Receitas recomendadas em workforce. Não criar hierarquia ilimitada de agentes: idealmente 1 implementador + 1 reviewer e no máximo 2 especialistas ativos, com delegação rasa. Instruções de agente não ampliam permissões reais.

7. Estado e migração

O repositório ainda está predominantemente em documentação. Comandos cargo, just, Slint MCP, VM e ISO não são garantidos até que arquivos e executáveis existam e passem em teste. Aplicar as regras a arquivos tocados, sem renomeações globais cegas ou “refactors” oportunistas.