docs: add Prometeu Engineering README

This commit is contained in:
Nilton Constantino
2026-11-16 15:22:02 +00:00
parent 96b84608ff
commit 63a5b9b145
13 changed files with 442 additions and 1 deletions
+1 -1
View File
@@ -1,3 +1,3 @@
---
schemaVersion: 2
lastWork: "0001"
lastWork: "0002"
@@ -0,0 +1,12 @@
---
schemaVersion: 1
id: "ART-0001"
workId: "WRK-0002"
origin: "Revisão local da documentação nesta sessão"
purpose: "Conferência dos links, comandos de referência, cadastro dos submódulos e\
\ integridade AIE."
path: "artifacts/evidence/ART-0001/payload"
sha256: "5a5ac6d3c67fa6154469fe6f1dc29f0bee5d0d088e9218e701d821f48c5d2985"
size: 1049
author: "codex"
createdAt: "2026-11-16T15:21:17.596766Z"
@@ -0,0 +1,37 @@
{
"file": "README.md",
"language": "pt-BR",
"verifiedLocalLinks": [
".ai-engineering/README.md",
".ai-engineering/ai-engineering.yaml",
".ai-engineering/protocol.json",
".gitignore",
".gitmodules",
"AGENTS.md",
"runtime/README.md",
"runtime/docs/specs/runtime/README.md",
"runtime/docs/vm-arch/ARCHITECTURE.md",
"runtime/rust-toolchain.toml",
"studio/README.md",
"studio/docs/specs/README.md",
"studio/docs/specs/compiler-languages/pbs/README.md",
"studio/docs/specs/compiler/README.md",
"studio/docs/specs/packer/README.md"
],
"commandsCheckedAgainst": [
"runtime/README.md",
"studio/README.md",
".ai-engineering/README.md"
],
"aieRepositories": [
"runtime",
"studio"
],
"aieValidation": {
"valid": true,
"issues": []
},
"formatChecks": "Links existentes, blocos de código fechados e nenhuma linha com whitespace final.",
"buildsAndTestsExecuted": false,
"scope": "Documentação da raiz; nenhum arquivo dos submódulos alterado."
}
@@ -0,0 +1,12 @@
---
schemaVersion: 1
id: "ART-0002"
workId: "WRK-0002"
origin: "ai-engineering:plans:2803d39a98459502e73c955be703622a8cc47dd69c7a569f4c43ee7ed6e073d7"
purpose: "Deterministic aggregation of completed Plans and reviewed cancellations;\
\ not semantic verification of prose criteria"
path: "artifacts/evidence/ART-0002/payload"
sha256: "2803d39a98459502e73c955be703622a8cc47dd69c7a569f4c43ee7ed6e073d7"
size: 283
author: "system:plans"
createdAt: "2026-11-16T15:21:18.142480Z"
@@ -0,0 +1,10 @@
{
"schemaVersion" : 1,
"workId" : "WRK-0002",
"inputHash" : "a51290e3dff5fb7c0a7d0ff332c35a98d9291d393a3dc7cc3b45c4183318e5c0",
"plans" : [ {
"id" : "PLN-0001",
"revision" : 5,
"sha256" : "507e309bdba50d03a4656516b6ce5ee54f71de57e88dba2db0e2daf96a17a87d"
} ]
}
@@ -0,0 +1,13 @@
---
schemaVersion: 1
id: "DSC-0001"
workId: "WRK-0002"
discussionId: "main"
kind: "NOTE"
author: "user"
createdAt: "2026-11-16T15:20:07.403258Z"
respondsTo: null
documentVersion: 2
---
Solicitação explícita nesta sessão: "escreva um README para o prometeu engineering." Escopo: documentação na raiz do workspace, mantendo somente runtime e studio como projetos versionados.
@@ -0,0 +1,18 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0002"
title: "Escrever e revisar o README do workspace"
decisions: []
steps: []
status: "OPEN"
author: "codex"
createdAt: "2026-11-16T15:20:07.665626Z"
revision: 1
previousHash: null
updatedAt: "2026-11-16T15:20:07.665626Z"
updatedBy: "codex"
changeReason: "Plan created"
documentVersion: 2
---
@@ -0,0 +1,29 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0002"
title: "Escrever e revisar o README do workspace"
decisions: []
steps:
- id: "TSK-0001"
title: "Escrever README em português e conferir referências e comandos locais"
description: ""
acceptanceCriteria:
- "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\
\ documentados; links e integridade AIE verificados."
dependsOn: []
status: "OPEN"
result: ""
evidence: []
updatedAt: "2026-11-16T15:20:08.090183Z"
status: "OPEN"
author: "codex"
createdAt: "2026-11-16T15:20:07.665626Z"
revision: 2
previousHash: "16f89cd1148f3383a1e267c63bc9b3e7618c263f883efc2bd944ab19ac5bfef9"
updatedAt: "2026-11-16T15:20:08.090212Z"
updatedBy: "codex"
changeReason: "Step added"
documentVersion: 2
---
@@ -0,0 +1,31 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0002"
title: "Escrever e revisar o README do workspace"
decisions: []
steps:
- id: "TSK-0001"
title: "Escrever README em português e conferir referências e comandos locais"
description: ""
acceptanceCriteria:
- "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\
\ documentados; links e integridade AIE verificados."
dependsOn: []
status: "ACTIVE"
result: "README escrito; conferindo links, exemplos e correspondência com a configuraç\
ão local."
evidence: []
updatedAt: "2026-11-16T15:21:08.185034Z"
status: "ACTIVE"
author: "codex"
createdAt: "2026-11-16T15:20:07.665626Z"
revision: 3
previousHash: "8bdd1fd4ecbfbb87e46bef9d9b004fd2c34b5361cebf0f08fcc3e966414d13dd"
updatedAt: "2026-11-16T15:21:08.185074Z"
updatedBy: "codex"
changeReason: "README escrito; conferindo links, exemplos e correspondência com a\
\ configuração local."
documentVersion: 2
---
@@ -0,0 +1,34 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0002"
title: "Escrever e revisar o README do workspace"
decisions: []
steps:
- id: "TSK-0001"
title: "Escrever README em português e conferir referências e comandos locais"
description: ""
acceptanceCriteria:
- "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\
\ documentados; links e integridade AIE verificados."
dependsOn: []
status: "COMPLETED"
result: "README em português criado com visão do workspace, submódulos, política\
\ de ignore, preparação, fluxo AIE, desenvolvimento e referências; links e comandos\
\ conferidos e validação AIE sem erros."
evidence:
- "ART-0001"
updatedAt: "2026-11-16T15:21:17.892124Z"
status: "ACTIVE"
author: "codex"
createdAt: "2026-11-16T15:20:07.665626Z"
revision: 4
previousHash: "15f998f0780319273c8b2772289fbf16b22c1b74795e81e3ae1141278fc901a4"
updatedAt: "2026-11-16T15:21:17.892152Z"
updatedBy: "codex"
changeReason: "README em português criado com visão do workspace, submódulos, polí\
tica de ignore, preparação, fluxo AIE, desenvolvimento e referências; links e comandos\
\ conferidos e validação AIE sem erros."
documentVersion: 2
---
@@ -0,0 +1,32 @@
---
schemaVersion: 1
id: "PLN-0001"
workId: "WRK-0002"
title: "Escrever e revisar o README do workspace"
decisions: []
steps:
- id: "TSK-0001"
title: "Escrever README em português e conferir referências e comandos locais"
description: ""
acceptanceCriteria:
- "Propósito, submódulos, ignore, início do trabalho com AIE e referências locais\
\ documentados; links e integridade AIE verificados."
dependsOn: []
status: "COMPLETED"
result: "README em português criado com visão do workspace, submódulos, política\
\ de ignore, preparação, fluxo AIE, desenvolvimento e referências; links e comandos\
\ conferidos e validação AIE sem erros."
evidence:
- "ART-0001"
updatedAt: "2026-11-16T15:21:17.892124Z"
status: "COMPLETED"
author: "codex"
createdAt: "2026-11-16T15:20:07.665626Z"
revision: 5
previousHash: "dc6be7ae04a25403541f097f49a4346829698b59c4652e760b7de7705111ae0e"
updatedAt: "2026-11-16T15:21:18.008863Z"
updatedBy: "system:plans"
changeReason: "All required steps completed; reviewed cancellations retained"
documentVersion: 2
---
@@ -0,0 +1,66 @@
---
schemaVersion: 1
id: "WRK-0002"
title: "Documentar o Prometeu Engineering no README da raiz"
description: ""
goal: "Apresentar o workspace, seus dois submódulos e o fluxo de engenharia com AIE\
\ em um README em português."
motivation: ""
constraints: []
acceptanceCriteria:
- "README.md explica propósito, runtime, studio, inicialização dos submódulos e polí\
tica de ignore."
- "README.md orienta o fluxo AIE e referencia documentação e comandos verificados\
\ nos arquivos locais."
status: "COMPLETED"
createdAt: "2026-11-16T15:19:58.000374Z"
updatedAt: "2026-11-16T15:21:18.154806Z"
author: "codex"
repositories: []
discussions:
- "DSC-0001"
decisions: []
artifacts:
- "ART-0001"
- "ART-0002"
plans:
- "PLN-0001"
completions:
- at: "2026-11-16T15:21:18.154806Z"
by: "system:plans"
summary: "All required Plans completed; requester=codex"
humanApproved: false
scopeHash: "e6d2bb5571a56ed8dbe62ee7b42da149cc11f146eaa642db7ad68f4f74fefbcd"
criteria:
- criterion: 1
text: "README.md explica propósito, runtime, studio, inicialização dos submódulos\
\ e política de ignore."
evidence:
- "ART-0002"
- criterion: 2
text: "README.md orienta o fluxo AIE e referencia documentação e comandos verificados\
\ nos arquivos locais."
evidence:
- "ART-0002"
integrations: []
noIntegrationReason: "Canonical changes and execution results are recorded in the\
\ Plan step evidence"
origin: "SYSTEM_PLANS"
delegation: null
aggregation:
receipt: "ART-0002"
inputHash: "a51290e3dff5fb7c0a7d0ff332c35a98d9291d393a3dc7cc3b45c4183318e5c0"
requester: "codex"
requestId: "0835f52b-b814-465d-9fa2-e5e6851f00e9"
events:
- action: "COMPLETE"
by: "system:plans"
reason: "All required Plans completed; requester=codex"
at: "2026-11-16T15:21:18.154806Z"
archived: false
topics: []
surveys: []
dispositions: []
agentRuns: []
epic: false
---
+147
View File
@@ -0,0 +1,147 @@
# 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.