Files

148 lines
5.4 KiB
Markdown

# 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.