# 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)](.ai-engineering/README.md): 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](runtime/README.md) | Execução da máquina: VM, periféricos, firmware, integração com o host e CLI. | Rust | | [studio](studio/README.md) | 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 ```text . ├── .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`](.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`](.gitmodules). Após clonar este repositório, execute na raiz: ```bash 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`](runtime/rust-toolchain.toml). Veja os requisitos completos no [README do runtime](runtime/README.md). - **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](studio/README.md). - **Engenharia:** CLI `aie` ou `ai-engineering` disponível no ambiente. ## Trabalhar com AIE Antes de iniciar trabalho de engenharia, leia o [AGENTS.md](AGENTS.md), o [guia do protocolo](.ai-engineering/README.md) e o [manifesto](.ai-engineering/protocol.json). 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: ```bash 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: ```bash aie work create "Descrever a alteração de integração" --repo runtime --repo studio ``` Carregue o contexto usando o identificador retornado, substituindo `WRK-XXXX`: ```bash 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: ```bash 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:** ```bash 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](runtime/README.md). **Studio**, a partir da raiz do workspace: ```bash 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](studio/README.md). 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 - [Especificações da máquina](runtime/docs/specs/runtime/README.md) - [Arquitetura da VM e runtime](runtime/docs/vm-arch/ARCHITECTURE.md) - [Guia de especificações do Studio](studio/docs/specs/README.md) - [Compilador](studio/docs/specs/compiler/README.md) - [Linguagem PBS e SDK](studio/docs/specs/compiler-languages/pbs/README.md) - [Empacotamento de assets](studio/docs/specs/packer/README.md) - [Configuração do AIE](.ai-engineering/ai-engineering.yaml) 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.