Files
prometeu-engineering/README.md
T

5.4 KiB

Prometeu Engineering

Workspace de engenharia do Prometeu, um console virtual educacional e experimental. Reúne os repositórios da plataforma e o contexto de trabalho em AI Engineering (AIE): discussões, decisões, planos e evidências de execução.

Projetos

Os únicos projetos integrados a este workspace são os submódulos Git abaixo, também cadastrados no AIE:

Projeto Responsabilidade Tecnologia
runtime Execução da máquina: VM, periféricos, firmware, integração com o host e CLI. Rust
studio Ambiente de desenvolvimento: interface desktop, compilador, empacotamento de assets e integração com execução e depuração. Java, JavaFX e Gradle

Cada submódulo mantém seu próprio histórico, especificações e comandos de validação. Este repositório registra as revisões usadas em conjunto e organiza o trabalho de engenharia do workspace.

Estrutura

.
├── .ai-engineering/   # Configuração, protocolo e Works do AIE
├── .gitignore        # Política de arquivos e diretórios locais
├── .gitmodules       # Origens dos dois submódulos
├── AGENTS.md         # Instruções de engenharia para agentes
├── README.md
├── runtime/          # Submódulo da máquina e runtime
└── studio/           # Submódulo do ambiente de desenvolvimento

O .gitignore ignora os demais diretórios na raiz, inclusive novos projetos locais. As exceções são runtime/, studio/ e .ai-engineering/. Os arquivos locais e temporários do AIE têm regras próprias de exclusão.

Preparar o workspace

É necessário ter Git e acesso SSH aos repositórios definidos em .gitmodules. Após clonar este repositório, execute na raiz:

git submodule update --init runtime studio
git submodule status

Esse comando carrega as revisões registradas pelo workspace. Após atualizar o repositório principal, execute novamente git submodule update --init runtime studio para alinhar os submódulos às revisões recebidas.

Para desenvolver, consulte os requisitos específicos de cada projeto:

  • Runtime: Rust via rustup, com a versão definida em rust-toolchain.toml. Veja os requisitos completos no README do runtime.
  • Studio: JDK e ambiente desktop para JavaFX; o Gradle Wrapper está incluído. Veja os requisitos e opções de instalação no README do Studio.
  • Engenharia: CLI aie ou ai-engineering disponível no ambiente.

Trabalhar com AIE

Antes de iniciar trabalho de engenharia, leia o AGENTS.md, o guia do protocolo e o manifesto. Consulte também as instruções locais do projeto que será alterado.

Na raiz do workspace, consulte o estado e as próximas ações:

aie status --format json
aie next-actions --format json
aie repo list --format json

Selecione um Work existente que corresponda à tarefa. Se não houver, crie um com objetivo e critérios de aceitação; associe apenas os repositórios envolvidos. Por exemplo, para uma alteração de integração:

aie work create "Descrever a alteração de integração" --repo runtime --repo studio

Carregue o contexto usando o identificador retornado, substituindo WRK-XXXX:

aie work context WRK-XXXX --format markdown

Registre discussões, decisões, planos e evidências no Work correspondente. Aprovações humanas devem ser explícitas, conforme o protocolo. A configuração atual cadastra os dois repositórios com acesso de leitura no AIE; esse cadastro não concede autorização de edição.

Para conferir a integridade dos registros:

aie project validate --format json

Se o alias aie não estiver disponível, use ai-engineering com os mesmos argumentos. Sem a CLI, consulte os arquivos portáveis em .ai-engineering/.

Desenvolvimento e validação

Execute os comandos no diretório do respectivo submódulo.

Runtime:

cd runtime
cargo build
make test

O gate de CI do runtime é make ci-domains; seus requisitos adicionais estão documentados no README do runtime.

Studio, a partir da raiz do workspace:

cd studio
./gradlew :prometeu-app:run
./gradlew test

As instruções de distribuição, cobertura e testes de integração estão no README do Studio.

As alterações de código são commitadas no submódulo correspondente. Depois, registre neste repositório a atualização do ponteiro de runtime ou studio, junto aos registros de engenharia relacionados. O commit da raiz referencia um commit do submódulo; os arquivos de código pertencem ao histórico desse projeto.

Referências

As especificações de cada projeto são a referência para seus contratos e comportamentos. O README da raiz orienta a navegação e o trabalho conjunto.