docs: prepare public README and distribute MIT license
This commit is contained in:
@@ -1,3 +1,3 @@
|
||||
---
|
||||
schemaVersion: 2
|
||||
lastWork: "0004"
|
||||
lastWork: "0006"
|
||||
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0005"
|
||||
origin: "aie-readme-generic-example.txt"
|
||||
purpose: "Verificação da remoção de referências ao piloto do README principal"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "2990a567d91a0bf785ba0104a335739082bb12a5b84881d5fe2263fc0b6c93ed"
|
||||
size: 372
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:42:10.844235Z"
|
||||
+1
@@ -0,0 +1 @@
|
||||
README.md atualizado por solicitação explícita do usuário: remover qualquer menção a Zelda1. O exemplo agora usa um projeto independente genérico, preservando o registro opcional de repositórios. Verificação textual case-insensitive: nenhuma ocorrência de zelda. git diff --check passou. Não foram executados testes de código para esta alteração editorial.
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0005"
|
||||
origin: "ai-engineering:plans:261a49281886ca015829aea8188f1782b51769430f9351966518b361fc05bc20"
|
||||
purpose: "Deterministic aggregation of completed Plans and reviewed cancellations;\
|
||||
\ not semantic verification of prose criteria"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "261a49281886ca015829aea8188f1782b51769430f9351966518b361fc05bc20"
|
||||
size: 283
|
||||
author: "system:plans"
|
||||
createdAt: "2026-11-16T10:42:11.801269Z"
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0005",
|
||||
"inputHash" : "93311e3a086147c0f89260e689c7a898c1d53d570dfe3c84cf5e18441f72cb19",
|
||||
"plans" : [ {
|
||||
"id" : "PLN-0001",
|
||||
"revision" : 4,
|
||||
"sha256" : "06fa822257b8e28bde476f039662eb4e0fd03b6e386cae2341f54e12809772e4"
|
||||
} ]
|
||||
}
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0005"
|
||||
title: "Generalizar o exemplo do README"
|
||||
decisions: []
|
||||
steps: []
|
||||
status: "OPEN"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:42:08.483231Z"
|
||||
revision: 1
|
||||
previousHash: null
|
||||
updatedAt: "2026-11-16T10:42:08.483231Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Plan created"
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0005"
|
||||
title: "Generalizar o exemplo do README"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Remover menções ao piloto e verificar o texto"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Ausência de Zelda no README principal e diff sem problemas."
|
||||
dependsOn: []
|
||||
status: "OPEN"
|
||||
result: ""
|
||||
evidence: []
|
||||
updatedAt: "2026-11-16T10:42:09.327263Z"
|
||||
status: "OPEN"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:42:08.483231Z"
|
||||
revision: 2
|
||||
previousHash: "444d521aff97d934726525ab1f9301fb94d2c43127a2793eea70681783849b5d"
|
||||
updatedAt: "2026-11-16T10:42:09.327301Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Step added"
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0005"
|
||||
title: "Generalizar o exemplo do README"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Remover menções ao piloto e verificar o texto"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Ausência de Zelda no README principal e diff sem problemas."
|
||||
dependsOn: []
|
||||
status: "COMPLETED"
|
||||
result: "Exemplo generalizado; nenhuma menção a Zelda no README e diff verificado."
|
||||
evidence:
|
||||
- "ART-0001"
|
||||
updatedAt: "2026-11-16T10:42:11.238817Z"
|
||||
status: "ACTIVE"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:42:08.483231Z"
|
||||
revision: 3
|
||||
previousHash: "f341d8a5039502303731a262142507d464f7f2230fe55680e3e2a6cda2e53413"
|
||||
updatedAt: "2026-11-16T10:42:11.238840Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Exemplo generalizado; nenhuma menção a Zelda no README e diff verificado."
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0005"
|
||||
title: "Generalizar o exemplo do README"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Remover menções ao piloto e verificar o texto"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Ausência de Zelda no README principal e diff sem problemas."
|
||||
dependsOn: []
|
||||
status: "COMPLETED"
|
||||
result: "Exemplo generalizado; nenhuma menção a Zelda no README e diff verificado."
|
||||
evidence:
|
||||
- "ART-0001"
|
||||
updatedAt: "2026-11-16T10:42:11.238817Z"
|
||||
status: "COMPLETED"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:42:08.483231Z"
|
||||
revision: 4
|
||||
previousHash: "925be5be3a029500776938845b9a86252ce01b50ca263863587bc569a3bc0205"
|
||||
updatedAt: "2026-11-16T10:42:11.552679Z"
|
||||
updatedBy: "system:plans"
|
||||
changeReason: "All required steps completed; reviewed cancellations retained"
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0005"
|
||||
title: "Remover referência ao piloto do README"
|
||||
description: ""
|
||||
goal: "Manter o README principal genérico, sem menções a Zelda1."
|
||||
motivation: ""
|
||||
constraints: []
|
||||
acceptanceCriteria:
|
||||
- "README.md não contém menções a Zelda e preserva a orientação sobre registro opcional\
|
||||
\ de repositórios."
|
||||
status: "COMPLETED"
|
||||
createdAt: "2026-11-16T10:42:07.528745Z"
|
||||
updatedAt: "2026-11-16T10:42:11.822288Z"
|
||||
author: "agent"
|
||||
repositories:
|
||||
- repositoryId: "ai-engineering"
|
||||
path: "."
|
||||
head: "dc495b8db570909402cb6fd3a309986a7770688c"
|
||||
dirty: false
|
||||
discussions: []
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
plans:
|
||||
- "PLN-0001"
|
||||
completions:
|
||||
- at: "2026-11-16T10:42:11.822288Z"
|
||||
by: "system:plans"
|
||||
summary: "All required Plans completed; requester=agent"
|
||||
humanApproved: false
|
||||
scopeHash: "da13428a698eee289da82ca367a6ef62954a72cbcc8af0c124ef25aa33b72b0c"
|
||||
criteria:
|
||||
- criterion: 1
|
||||
text: "README.md não contém menções a Zelda e preserva a orientação sobre registro\
|
||||
\ opcional de repositórios."
|
||||
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: "93311e3a086147c0f89260e689c7a898c1d53d570dfe3c84cf5e18441f72cb19"
|
||||
requester: "agent"
|
||||
requestId: "527bb6b2-29f7-49f9-9010-c38919008c7f"
|
||||
events:
|
||||
- action: "COMPLETE"
|
||||
by: "system:plans"
|
||||
reason: "All required Plans completed; requester=agent"
|
||||
at: "2026-11-16T10:42:11.822288Z"
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
+11
@@ -0,0 +1,11 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0001"
|
||||
workId: "WRK-0006"
|
||||
origin: "aie-public-readme-evidence.txt"
|
||||
purpose: "Verificação de onboarding público, links e distribuição da licença MIT"
|
||||
path: "artifacts/evidence/ART-0001/payload"
|
||||
sha256: "de124b047f5f08c13b570d0a4afba3ac8f9185c929e034b5c98e62a7c4982eda"
|
||||
size: 3071
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:52:12.676232Z"
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
WRK-0006 — README público e licença MIT
|
||||
|
||||
Pedido explícito: melhorar o README de um projeto público com licença MIT, preservando a remoção anterior de referências ao piloto.
|
||||
|
||||
README reescrito em inglês, com apresentação, capacidades, instalação JVM/nativa, início rápido, repositórios genéricos, integração com agentes, compatibilidade, desenvolvimento, documentação, contribuição e licença. Detalhes operacionais extensos foram substituídos por links aos guias existentes. Não há referências a pilotos, projetos privados, caminhos pessoais ou servidor Git privado no README.
|
||||
|
||||
LICENSE adicionado com o texto MIT e titular Nilton Constantino (nome constante da autoria Git), ano 2026. A escolha MIT foi expressamente fornecida pelo usuário. Jar/bootJar incluem META-INF/LICENSE; ZIP/TAR nativos incluem LICENSE ao lado de README e docs.
|
||||
|
||||
Verificado agora:
|
||||
- 24 links locais/âncoras resolvidos.
|
||||
- Início rápido executado como escrito, incluindo a função POSIX para JAR e troca de diretório, em projeto temporário isolado.
|
||||
- Exemplos api/web executados com repositórios Git descartáveis, sem tocar repositórios reais.
|
||||
- Configuração dos adaptadores Codex/Claude e diagnóstico de compatibilidade executados no projeto temporário, sem chamadas a modelos.
|
||||
- ./gradlew bootJar nativeDistZip nativeDistTar -x nativeCompile --console=plain passou. O executável nativo existente foi reempacotado; não foi alegada nova compilação nativa.
|
||||
- JAR contém o LICENSE exato; ZIP/TAR contêm LICENSE e README idênticos aos fontes atuais.
|
||||
- git diff --check passou; aie project validate retornou valid=true, issues=[].
|
||||
|
||||
Não foi reexecutada a suíte completa de código para esta alteração editorial/metadados de empacotamento. Os exemplos de build nativo/SDKMAN não foram repetidos; foram conferidos contra a configuração versionada e a compilação nativa já executada nesta sessão. agent doctor não é exigido na verificação porque a presença de CLIs de terceiros é opcional; as opções documentadas foram conferidas no --help.
|
||||
|
||||
Resultados e hashes:
|
||||
{
|
||||
"demo": "/var/folders/0t/tfsqc14j5wbgh9h4s4dytwb00000gq/T/aie-public-readme-p7_y0y9h",
|
||||
"localLinks": 24,
|
||||
"shellBlocks": 9,
|
||||
"quickStartPassed": true,
|
||||
"repositoryExamplePassed": true,
|
||||
"agentConfigurationPassed": true,
|
||||
"compatibilityPassed": true,
|
||||
"privateReferencesFound": false,
|
||||
"packages": {
|
||||
"build/libs/ai-engineering-0.1.0.jar": {
|
||||
"license": "META-INF/LICENSE"
|
||||
},
|
||||
"build/distributions/ai-engineering-0.1.0-mac-os-x-aarch64.tar.gz": {
|
||||
"license": "LICENSE",
|
||||
"readmeMatchesSource": true
|
||||
},
|
||||
"build/distributions/ai-engineering-0.1.0-mac-os-x-aarch64.zip": {
|
||||
"license": "LICENSE",
|
||||
"readmeMatchesSource": true
|
||||
}
|
||||
},
|
||||
"readmeLines": 230,
|
||||
"readmeSha256": "0cc20053e0874aac59c7c8a77dc9535a7b8ae5a96cb806188e925bdfe85f1caa",
|
||||
"licenseSha256": "975eef35ea2ca6532c53302a8bf202b99231cc7387ebbb022b1af1d58e4852b6"
|
||||
}
|
||||
|
||||
build.gradle.kts SHA-256: 5a386507208dee521f99043f62d758b580a6d278ed22d045ee82d0cc6305a5dd
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "ART-0002"
|
||||
workId: "WRK-0006"
|
||||
origin: "ai-engineering:plans:eee36d8122bbad8bbd8013f823b3e6112b1db0d75cc2ef4c84437a83290bbd9a"
|
||||
purpose: "Deterministic aggregation of completed Plans and reviewed cancellations;\
|
||||
\ not semantic verification of prose criteria"
|
||||
path: "artifacts/evidence/ART-0002/payload"
|
||||
sha256: "eee36d8122bbad8bbd8013f823b3e6112b1db0d75cc2ef4c84437a83290bbd9a"
|
||||
size: 283
|
||||
author: "system:plans"
|
||||
createdAt: "2026-11-16T10:52:15.068458Z"
|
||||
+10
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"schemaVersion" : 1,
|
||||
"workId" : "WRK-0006",
|
||||
"inputHash" : "a0f9e8fe82ef06b289a0a825802a7f6d4fab02d3f1788831f1d7a18991f61b3e",
|
||||
"plans" : [ {
|
||||
"id" : "PLN-0001",
|
||||
"revision" : 7,
|
||||
"sha256" : "a177b558f456203fcb509c245289441056b4a6e8e1857dcff38bb59e0f96864b"
|
||||
} ]
|
||||
}
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "DSC-0001"
|
||||
workId: "WRK-0006"
|
||||
discussionId: "main"
|
||||
kind: "NOTE"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:53.622119Z"
|
||||
respondsTo: null
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
Autorização explícita do usuário: melhorar README para projeto público com licença MIT, preservando a remoção anterior de referências ao piloto. O repositório ainda não tem LICENSE; incluir o texto MIT e empacotá-lo com JAR/arquivos nativos torna a seção de licença concreta. Não publicar, criar releases, alterar código de produção ou reabrir Works concluídos.
|
||||
+18
@@ -0,0 +1,18 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0006"
|
||||
title: "Documentação pública e licença distribuível"
|
||||
decisions: []
|
||||
steps: []
|
||||
status: "OPEN"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:54.025777Z"
|
||||
revision: 1
|
||||
previousHash: null
|
||||
updatedAt: "2026-11-16T10:46:54.025777Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Plan created"
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0006"
|
||||
title: "Documentação pública e licença distribuível"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Reescrever README e adicionar licença MIT aos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Onboarding público conciso, sem projetos privados; LICENSE real incluído na distribuiç\
|
||||
ão."
|
||||
dependsOn: []
|
||||
status: "OPEN"
|
||||
result: ""
|
||||
evidence: []
|
||||
updatedAt: "2026-11-16T10:46:55.295769Z"
|
||||
status: "OPEN"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:54.025777Z"
|
||||
revision: 2
|
||||
previousHash: "c307352921d4ad34a76366e46a406d299803595d0ed42bd49b311d675eb7a5a9"
|
||||
updatedAt: "2026-11-16T10:46:55.295824Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Step added"
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0006"
|
||||
title: "Documentação pública e licença distribuível"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Reescrever README e adicionar licença MIT aos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Onboarding público conciso, sem projetos privados; LICENSE real incluído na distribuiç\
|
||||
ão."
|
||||
dependsOn: []
|
||||
status: "OPEN"
|
||||
result: ""
|
||||
evidence: []
|
||||
updatedAt: "2026-11-16T10:46:55.295769Z"
|
||||
- id: "TSK-0002"
|
||||
title: "Verificar exemplos, links e conteúdo dos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Exemplos executam em projeto descartável; links locais resolvem; JAR/ZIP/TAR\
|
||||
\ contêm licença."
|
||||
dependsOn:
|
||||
- "TSK-0001"
|
||||
status: "OPEN"
|
||||
result: ""
|
||||
evidence: []
|
||||
updatedAt: "2026-11-16T10:46:57.015487Z"
|
||||
status: "OPEN"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:54.025777Z"
|
||||
revision: 3
|
||||
previousHash: "a04985fefab638200c4ce0a604695e4656bd0e37fcefed1a493b4cdb950314fc"
|
||||
updatedAt: "2026-11-16T10:46:57.015506Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Step added"
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+41
@@ -0,0 +1,41 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0006"
|
||||
title: "Documentação pública e licença distribuível"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Reescrever README e adicionar licença MIT aos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Onboarding público conciso, sem projetos privados; LICENSE real incluído na distribuiç\
|
||||
ão."
|
||||
dependsOn: []
|
||||
status: "ACTIVE"
|
||||
result: "Revisão pública do README autorizada pelo usuário."
|
||||
evidence: []
|
||||
updatedAt: "2026-11-16T10:46:58.089024Z"
|
||||
- id: "TSK-0002"
|
||||
title: "Verificar exemplos, links e conteúdo dos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Exemplos executam em projeto descartável; links locais resolvem; JAR/ZIP/TAR\
|
||||
\ contêm licença."
|
||||
dependsOn:
|
||||
- "TSK-0001"
|
||||
status: "OPEN"
|
||||
result: ""
|
||||
evidence: []
|
||||
updatedAt: "2026-11-16T10:46:57.015487Z"
|
||||
status: "ACTIVE"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:54.025777Z"
|
||||
revision: 4
|
||||
previousHash: "2e7be384b1e722ae203b1f1f099f0fa2704f48b1f561c7732a8c476cb8d600fb"
|
||||
updatedAt: "2026-11-16T10:46:58.089043Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Revisão pública do README autorizada pelo usuário."
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0006"
|
||||
title: "Documentação pública e licença distribuível"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Reescrever README e adicionar licença MIT aos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Onboarding público conciso, sem projetos privados; LICENSE real incluído na distribuiç\
|
||||
ão."
|
||||
dependsOn: []
|
||||
status: "COMPLETED"
|
||||
result: "README público genérico e licença MIT implementados, com licença nos artefatos\
|
||||
\ distribuíveis."
|
||||
evidence:
|
||||
- "ART-0001"
|
||||
updatedAt: "2026-11-16T10:52:13.092276Z"
|
||||
- id: "TSK-0002"
|
||||
title: "Verificar exemplos, links e conteúdo dos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Exemplos executam em projeto descartável; links locais resolvem; JAR/ZIP/TAR\
|
||||
\ contêm licença."
|
||||
dependsOn:
|
||||
- "TSK-0001"
|
||||
status: "OPEN"
|
||||
result: ""
|
||||
evidence: []
|
||||
updatedAt: "2026-11-16T10:46:57.015487Z"
|
||||
status: "ACTIVE"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:54.025777Z"
|
||||
revision: 5
|
||||
previousHash: "10047e4940d55af2d1e10a84ed3544e253ade72b458f5949587dd84e48ed6a60"
|
||||
updatedAt: "2026-11-16T10:52:13.092296Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "README público genérico e licença MIT implementados, com licença nos\
|
||||
\ artefatos distribuíveis."
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0006"
|
||||
title: "Documentação pública e licença distribuível"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Reescrever README e adicionar licença MIT aos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Onboarding público conciso, sem projetos privados; LICENSE real incluído na distribuiç\
|
||||
ão."
|
||||
dependsOn: []
|
||||
status: "COMPLETED"
|
||||
result: "README público genérico e licença MIT implementados, com licença nos artefatos\
|
||||
\ distribuíveis."
|
||||
evidence:
|
||||
- "ART-0001"
|
||||
updatedAt: "2026-11-16T10:52:13.092276Z"
|
||||
- id: "TSK-0002"
|
||||
title: "Verificar exemplos, links e conteúdo dos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Exemplos executam em projeto descartável; links locais resolvem; JAR/ZIP/TAR\
|
||||
\ contêm licença."
|
||||
dependsOn:
|
||||
- "TSK-0001"
|
||||
status: "COMPLETED"
|
||||
result: "Exemplos e 24 links verificados; JAR, ZIP e TAR construídos e licença/README\
|
||||
\ conferidos; projeto validado."
|
||||
evidence:
|
||||
- "ART-0001"
|
||||
updatedAt: "2026-11-16T10:52:14.245461Z"
|
||||
status: "ACTIVE"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:54.025777Z"
|
||||
revision: 6
|
||||
previousHash: "b253affe2c17ff68d19f938629610fae31e3d9c2ce9d2cbebbb87eff0b134a14"
|
||||
updatedAt: "2026-11-16T10:52:14.245480Z"
|
||||
updatedBy: "agent"
|
||||
changeReason: "Exemplos e 24 links verificados; JAR, ZIP e TAR construídos e licenç\
|
||||
a/README conferidos; projeto validado."
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "PLN-0001"
|
||||
workId: "WRK-0006"
|
||||
title: "Documentação pública e licença distribuível"
|
||||
decisions: []
|
||||
steps:
|
||||
- id: "TSK-0001"
|
||||
title: "Reescrever README e adicionar licença MIT aos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Onboarding público conciso, sem projetos privados; LICENSE real incluído na distribuiç\
|
||||
ão."
|
||||
dependsOn: []
|
||||
status: "COMPLETED"
|
||||
result: "README público genérico e licença MIT implementados, com licença nos artefatos\
|
||||
\ distribuíveis."
|
||||
evidence:
|
||||
- "ART-0001"
|
||||
updatedAt: "2026-11-16T10:52:13.092276Z"
|
||||
- id: "TSK-0002"
|
||||
title: "Verificar exemplos, links e conteúdo dos pacotes"
|
||||
description: ""
|
||||
acceptanceCriteria:
|
||||
- "Exemplos executam em projeto descartável; links locais resolvem; JAR/ZIP/TAR\
|
||||
\ contêm licença."
|
||||
dependsOn:
|
||||
- "TSK-0001"
|
||||
status: "COMPLETED"
|
||||
result: "Exemplos e 24 links verificados; JAR, ZIP e TAR construídos e licença/README\
|
||||
\ conferidos; projeto validado."
|
||||
evidence:
|
||||
- "ART-0001"
|
||||
updatedAt: "2026-11-16T10:52:14.245461Z"
|
||||
status: "COMPLETED"
|
||||
author: "agent"
|
||||
createdAt: "2026-11-16T10:46:54.025777Z"
|
||||
revision: 7
|
||||
previousHash: "57469deddb86109555a6fef9ff3ddf2897da4541801395668b5354c1bf4b8d8e"
|
||||
updatedAt: "2026-11-16T10:52:14.653491Z"
|
||||
updatedBy: "system:plans"
|
||||
changeReason: "All required steps completed; reviewed cancellations retained"
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: "WRK-0006"
|
||||
title: "Preparar README público e licença MIT"
|
||||
description: ""
|
||||
goal: "Apresentar o AIE como projeto público com onboarding claro, exemplos genéricos\
|
||||
\ e licença MIT explícita."
|
||||
motivation: ""
|
||||
constraints:
|
||||
- "Preservar a remoção de referências ao piloto e os Works concluídos."
|
||||
acceptanceCriteria:
|
||||
- "README em inglês apresenta propósito, requisitos, instalação, início rápido, documentaç\
|
||||
ão e contribuição sem referências a projetos privados ou pilotos."
|
||||
- "Licença MIT está disponível e acompanhando os artefatos distribuíveis; links e\
|
||||
\ exemplos públicos são verificados."
|
||||
status: "COMPLETED"
|
||||
createdAt: "2026-11-16T10:46:52.759357Z"
|
||||
updatedAt: "2026-11-16T10:52:15.102260Z"
|
||||
author: "agent"
|
||||
repositories:
|
||||
- repositoryId: "ai-engineering"
|
||||
path: "."
|
||||
head: "dc495b8db570909402cb6fd3a309986a7770688c"
|
||||
dirty: true
|
||||
discussions:
|
||||
- "DSC-0001"
|
||||
decisions: []
|
||||
artifacts:
|
||||
- "ART-0001"
|
||||
- "ART-0002"
|
||||
plans:
|
||||
- "PLN-0001"
|
||||
completions:
|
||||
- at: "2026-11-16T10:52:15.102260Z"
|
||||
by: "system:plans"
|
||||
summary: "All required Plans completed; requester=agent"
|
||||
humanApproved: false
|
||||
scopeHash: "74424246dff759a4a7df4f95ea5b8d8a24fff49dfdee651c01ae0630166baf45"
|
||||
criteria:
|
||||
- criterion: 1
|
||||
text: "README em inglês apresenta propósito, requisitos, instalação, início rá\
|
||||
pido, documentação e contribuição sem referências a projetos privados ou pilotos."
|
||||
evidence:
|
||||
- "ART-0002"
|
||||
- criterion: 2
|
||||
text: "Licença MIT está disponível e acompanhando os artefatos distribuíveis;\
|
||||
\ links e exemplos públicos são verificados."
|
||||
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: "a0f9e8fe82ef06b289a0a825802a7f6d4fab02d3f1788831f1d7a18991f61b3e"
|
||||
requester: "agent"
|
||||
requestId: "93fe06e5-6970-463f-b3f7-f8f477cd8bd1"
|
||||
events:
|
||||
- action: "COMPLETE"
|
||||
by: "system:plans"
|
||||
reason: "All required Plans completed; requester=agent"
|
||||
at: "2026-11-16T10:52:15.102260Z"
|
||||
archived: false
|
||||
topics: []
|
||||
surveys: []
|
||||
dispositions: []
|
||||
agentRuns: []
|
||||
epic: false
|
||||
---
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Nilton Constantino
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -1,491 +1,230 @@
|
||||
# ai-engineering
|
||||
# AI Engineering
|
||||
|
||||
An open, agent-agnostic engineering protocol and CLI for simple projects and projects
|
||||
spanning multiple repositories. Git is optional. Works belong to the engineering
|
||||
project. Canonical files preserve goals, discussion,
|
||||
decisions, plans and evidence so another person or agent can continue without chat history.
|
||||
[MIT License](LICENSE) · [Quick start](#quick-start) · [Documentation](#documentation) · [Contributing](#contributing)
|
||||
|
||||
Milestones 0 and 1 and the operational replacement baseline are implemented.
|
||||
Discussion refinement now includes topics, surveys and two deterministic adapters
|
||||
to verify the integration contract. Local Codex/Claude adapters now exercise that
|
||||
contract with real providers for proposals and synthesis.
|
||||
The application runs locally in non-web mode;
|
||||
it needs no model API, database or running service.
|
||||
AI Engineering (AIE) is a local CLI for keeping engineering work understandable
|
||||
across people, AI agents, and sessions. It stores goals, discussions, decisions,
|
||||
plans, and verification evidence as readable files alongside your project.
|
||||
|
||||
## Build and run
|
||||
Use it in a single folder or across several source repositories. Git is optional.
|
||||
The core workflow runs without a model API, database, or background service.
|
||||
|
||||
Build requirements: JDK 25, Git (for repository inspection and integration fixtures),
|
||||
and internet access for the first dependency download. The Gradle Wrapper is included.
|
||||
## What you can do
|
||||
|
||||
The recommended local toolchain is GraalVM Community Edition, pinned in `.sdkmanrc`.
|
||||
With SDKMAN installed, activate it from the project root:
|
||||
- **Preserve context:** resume a Work from recorded goals, discussion, decisions,
|
||||
and evidence instead of relying on chat history.
|
||||
- **Refine ideas:** organize topics, collect answers through surveys, and retain
|
||||
the history when an answer or decision changes.
|
||||
- **Track delivery:** connect plans, dependencies, observed results, and evidence;
|
||||
consolidate completed plans through deterministic checks.
|
||||
- **Coordinate repositories:** explicitly select the repositories involved in each
|
||||
Work, while keeping engineering records in one project.
|
||||
- **Work with AI agents:** provide portable entry instructions and structured
|
||||
context; optionally use local Codex or Claude CLIs for proposals and summaries.
|
||||
- **Retain history:** read supported older formats without rewriting completed
|
||||
Works, approvals, or evidence.
|
||||
|
||||
A **Work** is the unit of engineering activity: a scoped problem or change with
|
||||
its own context and history. Decisions and plans are added when the work needs them.
|
||||
AIE records the work and checks its structure; people and agents choose solutions,
|
||||
change source code, run tests, and assess the results.
|
||||
|
||||
## Installation
|
||||
|
||||
### Run from source
|
||||
|
||||
Clone this repository and open its root directory. Building the JVM application
|
||||
requires **JDK 25** and access to dependency repositories on the first build.
|
||||
The Gradle Wrapper is included; a separate Gradle installation is unnecessary.
|
||||
|
||||
```sh
|
||||
sdk env install # only needed if the pinned JDK is not installed
|
||||
sdk env
|
||||
export GRAALVM_HOME="$JAVA_HOME"
|
||||
java --version
|
||||
native-image --version
|
||||
```
|
||||
|
||||
SDKMAN candidate `25.5.5.0+3-graalce` provides GraalVM CE 25.5.5.0.3 based on
|
||||
JDK 25.0.5.0.3. The Java language/bytecode target remains 25. SDKMAN is optional;
|
||||
setting `JAVA_HOME` and `GRAALVM_HOME` to an equivalent GraalVM installation also works.
|
||||
|
||||
```sh
|
||||
./gradlew clean test
|
||||
./gradlew bootJar
|
||||
java -jar build/libs/ai-engineering-0.1.0.jar --help
|
||||
java -jar build/libs/ai-engineering-0.1.0.jar --version
|
||||
```
|
||||
|
||||
Pinned stack: Java target 25, Spring Boot 4.0.9, Spring Modulith 2.0.9,
|
||||
Gradle 9.3.1, Picocli 4.7.7, Native Build Tools 0.11.5, JUnit 5.13.4.
|
||||
Jackson YAML/JSON and AssertJ versions come from the pinned Spring Boot BOM.
|
||||
Compatibility sources and rationale are in [architecture](docs/architecture.md).
|
||||
|
||||
## Native installation and packaging
|
||||
|
||||
A native distribution contains `ai-engineering` (`ai-engineering.exe` on Windows).
|
||||
Extract the platform archive and put that executable on `PATH`. Running it requires
|
||||
no JVM. Git must be on `PATH` for commands that inspect registered repositories.
|
||||
There are no published release downloads yet; packaging tasks create local archives.
|
||||
|
||||
Building requires GraalVM for **JDK 25**, Native Image and the host C/C++ toolchain:
|
||||
Xcode Command Line Tools on macOS, GCC and development libraries on Linux, or the
|
||||
Visual Studio C++ build tools on Windows. Set `JAVA_HOME` and `GRAALVM_HOME` to the
|
||||
GraalVM JDK home (`Contents/Home` on macOS).
|
||||
When SDKMAN's `current` points to another JDK, set both variables explicitly;
|
||||
Gradle's `org.gradle.java.home` alone does not select the Native Image tool.
|
||||
For the examples below, you can define a command in your current POSIX shell.
|
||||
Run this from the repository root so the JAR path stays valid after changing folders:
|
||||
|
||||
```sh
|
||||
export AIE_JAR="$PWD/build/libs/ai-engineering-0.1.0.jar"
|
||||
ai-engineering() { java -jar "$AIE_JAR" "$@"; }
|
||||
```
|
||||
|
||||
The JAR requires Java 25 at runtime. On Windows, use `gradlew.bat` in place of
|
||||
`./gradlew`; you can invoke the JAR directly with `java -jar` and its full path.
|
||||
|
||||
### Build a native executable
|
||||
|
||||
The native executable runs without a JVM. Building it requires **GraalVM for
|
||||
JDK 25**, Native Image, and a C/C++ toolchain for the target platform. Set both
|
||||
`JAVA_HOME` and `GRAALVM_HOME` to your GraalVM installation.
|
||||
|
||||
If you use SDKMAN, the repository pins a compatible toolchain in [.sdkmanrc](.sdkmanrc):
|
||||
|
||||
```sh
|
||||
sdk env install
|
||||
sdk env
|
||||
export GRAALVM_HOME="$JAVA_HOME"
|
||||
./gradlew nativeCompile
|
||||
./build/native/nativeCompile/ai-engineering --help
|
||||
./gradlew nativeDistZip nativeDistTar -PtargetPlatform=macos-arm64
|
||||
bash scripts/native-smoke.sh "$PWD/build/native/nativeCompile/ai-engineering"
|
||||
```
|
||||
|
||||
Archives are written to `build/distributions/ai-engineering-0.1.0-<platform>.*`.
|
||||
Build each binary on its target OS/architecture; Native Image is not a general cross
|
||||
compiler. CI defines Linux x86_64, macOS ARM64 and Windows x86_64 native builds.
|
||||
macOS x86_64 remains a target with an upstream toolchain availability limitation:
|
||||
GraalVM 25 dropped that port; see [roadmap](docs/roadmap.md). Local verification
|
||||
results, including which native binaries were actually tested, are in [experiments](docs/experiments.md).
|
||||
Add the executable's directory to `PATH` to use `ai-engineering` from other folders.
|
||||
On Windows the executable is named `ai-engineering.exe`. The shorter `aie` command
|
||||
can be provided as a local alias or symlink.
|
||||
|
||||
## Jenkins tests and coverage
|
||||
|
||||
The Jenkins pipeline is [files/config/Jenkinsfile](files/config/Jenkinsfile). Configure
|
||||
that Script Path in a Pipeline from SCM job on a Unix agent with JDK 25 and Git.
|
||||
It runs tests with JaCoCo and publishes JUnit, coverage XML/HTML and raw execution
|
||||
data, including available diagnostics after failures. Coverage gates follow Studio.
|
||||
To create distribution archives:
|
||||
|
||||
```sh
|
||||
./gradlew test jacocoTestReport jenkinsPipelineTest --continue --console=plain
|
||||
./gradlew nativeDistZip nativeDistTar
|
||||
```
|
||||
|
||||
Coverage HTML is generated at
|
||||
`build/reports/jacoco/jacocoTestReport/html/index.html`. See the
|
||||
[Jenkins setup and verification guide](files/config/README.md) for required plugins,
|
||||
thresholds, report paths and the boundary between local checks and a controller run.
|
||||
Archives are written to `build/distributions/` and include the README, documentation,
|
||||
and MIT license. Build on the intended OS and architecture; the native CI matrix
|
||||
is defined in [.github/workflows/build.yml](.github/workflows/build.yml).
|
||||
|
||||
## Start in a simple project
|
||||
## Quick start
|
||||
|
||||
Run inside the folder you already use for your application, game or library:
|
||||
With the CLI available, create an engineering workspace in a new folder:
|
||||
|
||||
```sh
|
||||
ai-engineering init --name "My Application"
|
||||
ai-engineering work create "Improve the application" \
|
||||
--goal "Preserve enough context to continue in another session"
|
||||
ai-engineering discussion add WRK-0001 --text "Record the current state and next questions."
|
||||
ai-engineering decision draft WRK-0001 --title "Evaluate the proposed approach"
|
||||
mkdir my-project
|
||||
cd my-project
|
||||
|
||||
ai-engineering init --name "My Project"
|
||||
ai-engineering work create "Improve configuration errors" \
|
||||
--goal "Make invalid configuration easier to diagnose" \
|
||||
--acceptance "Invalid configuration produces an actionable error"
|
||||
ai-engineering discussion add WRK-0001 --kind NOTE --author human \
|
||||
--text "Record the current behavior before choosing a solution."
|
||||
|
||||
ai-engineering status --format json
|
||||
ai-engineering next-actions --format json
|
||||
ai-engineering work context WRK-0001 --format markdown
|
||||
ai-engineering project validate
|
||||
```
|
||||
|
||||
This creates `.ai-engineering/` beside your existing source files. A project with
|
||||
`repositories: []` is fully supported; the workflow above does not require Git to be
|
||||
installed. Its Works have no Git revision snapshots. Git becomes relevant when you
|
||||
choose to register repositories.
|
||||
`init` creates `.ai-engineering/` and installs portable instructions for agents,
|
||||
including a managed block in the project's `AGENTS.md`. Existing project rules
|
||||
outside that block are preserved. Keep the canonical engineering files under
|
||||
version control when you use Git; `.ai-engineering/.local/` contains local state.
|
||||
|
||||
If the project folder is itself an existing Git repository, you can register it:
|
||||
The exported context brings together the Work's scope, discussion, decisions,
|
||||
plans, evidence references, and pending questions. `next-actions` suggests what to
|
||||
address next. Every command provides `--help`; inspection commands support JSON.
|
||||
|
||||
### Use existing Git repositories
|
||||
|
||||
Git is required when registering or inspecting source repositories. In a project
|
||||
that already contains `api/` and `web/` Git repositories, register them explicitly:
|
||||
|
||||
```sh
|
||||
ai-engineering repo add app --path .
|
||||
ai-engineering work create "Investigate a change" --repo app
|
||||
ai-engineering repo add api --path api --language java
|
||||
ai-engineering repo add web --path web --language typescript
|
||||
ai-engineering work create "Improve request validation" --repo api --repo web
|
||||
```
|
||||
|
||||
Registration is optional and defaults to read-only. For example, a standalone
|
||||
`zelda-1/` project can keep `.ai-engineering/` directly inside `zelda-1/`, without
|
||||
registering the separate runtime or editor repositories. Each Work explicitly selects
|
||||
any registered repositories it needs with `--repo`.
|
||||
For a project whose root is itself a Git repository, use `repo add app --path .`.
|
||||
Registration defaults to read-only access and does not change Git configuration.
|
||||
Each Work selects its repositories with `--repo`; registration is optional for
|
||||
projects that only need engineering records.
|
||||
|
||||
## Discover and continue with an agent
|
||||
## How work is recorded
|
||||
|
||||
`init` installs `.ai-engineering/README.md`, `AGENTS.md` and `protocol.json`. These
|
||||
describe the protocol without a provider-specific skill. It also creates or updates
|
||||
a marked AIE block in the project's root `AGENTS.md`, preserving rules outside the
|
||||
block. Changed instruction files are backed up under `.local/backups/onboarding/`.
|
||||
For an existing project, install the entry contract explicitly:
|
||||
| Record | Purpose |
|
||||
|---|---|
|
||||
| Work | Goal, constraints, acceptance criteria, and lifecycle |
|
||||
| Discussion | Observations, questions, proposals, and conclusions |
|
||||
| Survey | Questions with suggested choices, free text, and answer history |
|
||||
| Decision | A reviewed choice with explicit approval and revision history |
|
||||
| Plan | Steps, dependencies, observed results, and evidence references |
|
||||
| Artifact | Retained evidence with integrity metadata |
|
||||
|
||||
Completed required plans can consolidate a Work automatically. The framework
|
||||
checks recorded state and evidence integrity; it does not prove that arbitrary
|
||||
acceptance criteria have been satisfied. Human approvals are recorded explicitly,
|
||||
and system completion retains its own provenance.
|
||||
|
||||
See the [protocol reference](docs/protocol.md) for commands, formats, lifecycle
|
||||
rules, and recovery behavior.
|
||||
|
||||
## AI agent integration
|
||||
|
||||
Agents can discover the protocol through `AGENTS.md` and `.ai-engineering/`.
|
||||
They start with `status`, `next-actions`, and `work context` to reconstruct the
|
||||
current state. The entry contract is independent of any model provider.
|
||||
|
||||
Optional local adapters integrate installed, authenticated Codex and Claude CLIs:
|
||||
|
||||
```sh
|
||||
aie onboard
|
||||
aie status --format json
|
||||
aie next-actions --format json
|
||||
aie work context WRK-0001
|
||||
ai-engineering agent doctor --format json
|
||||
ai-engineering agent configure --adapter codex-cli --profile general --model default
|
||||
ai-engineering agent configure --activity analyze --adapter claude-cli --profile reviewer
|
||||
```
|
||||
|
||||
Use `ai-engineering` if the optional `aie` alias is unavailable. `onboard` is
|
||||
idempotent; it leaves Work records unchanged. `aie guide` reads the bundled guide
|
||||
even outside a project; `aie guide --format json` shows the discovery manifest.
|
||||
An agent that finds `.ai-engineering` can read its README and manifest directly.
|
||||
The root instructions point agents to that entry. Automatic discovery still depends
|
||||
on the agent inspecting project instructions; a CLI cannot force an arbitrary model
|
||||
to inspect hidden folders or obey a protocol. Exported context includes the guide.
|
||||
Adapters produce proposals and summaries that AIE validates before applying.
|
||||
Provider authentication remains with the provider's CLI. Offline fixture adapters
|
||||
are available for deterministic tests. See the [local CLI adapter guide](docs/cli-adapters.md)
|
||||
for setup, invocation controls, provenance, and supported behavior.
|
||||
|
||||
## Inspect compatibility before updating
|
||||
## Compatibility and updates
|
||||
|
||||
Inspect a project before considering a format update:
|
||||
|
||||
```sh
|
||||
aie project compatibility --format json
|
||||
ai-engineering project compatibility --format json
|
||||
ai-engineering project validate --format json
|
||||
```
|
||||
|
||||
`status` includes a compatibility summary. The diagnostic separates the installed
|
||||
CLI release, protocol contract revision and actual storage formats, including record
|
||||
history. `CURRENT` and `LEGACY_COMPATIBLE` both mean readable; neither requires a
|
||||
migration. `UNSUPPORTED` and `INVALID` return exit 4 and identify affected files.
|
||||
Validation of references and evidence remains `aie project validate`.
|
||||
`CURRENT` and `LEGACY_COMPATIBLE` both indicate readable formats. Supported older
|
||||
records remain readable without automatic normalization or reopening completed
|
||||
Works. `onboard` refreshes entry instructions with backups while preserving Work
|
||||
files. The [compatibility guide](docs/compatibility.md) explains contract versions,
|
||||
storage formats, diagnostics, and future explicit migrations.
|
||||
|
||||
Keep completed Works in their existing formats. Older supported files are interpreted
|
||||
in memory; reads and diagnostics never normalize them on disk. `aie onboard` updates
|
||||
only entry instructions and the manifest, with backups. It refuses to overwrite a
|
||||
newer unsupported contract. There is no required data migration in this release.
|
||||
See [compatibility and evolution](docs/compatibility.md) for the version policy and
|
||||
the contract for future migrations; no source-code inspection is needed by consumers.
|
||||
## Development and verification
|
||||
|
||||
## Discuss topics and answer surveys
|
||||
|
||||
Ideas remain Discussion entries, organized by Work-local topics. Existing discussion
|
||||
threads appear as implicit topics without rewriting their files. A small Work starts
|
||||
with topic `main`. Every survey question has suggestions and accepts free text:
|
||||
The test suite requires JDK 25 and Git. Run the project checks with:
|
||||
|
||||
```sh
|
||||
aie topic create WRK-0001 "Rendering"
|
||||
aie discussion add WRK-0001 --topic TOP-0001 --kind SUGGESTION \
|
||||
--text "Compare two rendering approaches" --author agent
|
||||
aie survey create WRK-0001 --title "Choose an investigation"
|
||||
aie survey question WRK-0001 SVY-0001 --topic TOP-0001 \
|
||||
--text "Which approach should we investigate?" \
|
||||
--option "Measure the current renderer" --option "Prototype layers" --recommend 1
|
||||
aie survey show WRK-0001 SVY-0001
|
||||
aie survey answer WRK-0001 SVY-0001 QST-0001 --choice 1 --author human
|
||||
# A new answer supersedes the previous one while preserving it:
|
||||
aie survey answer WRK-0001 SVY-0001 QST-0001 \
|
||||
--text "Compare both with a small fixture" --author human
|
||||
aie survey history WRK-0001 SVY-0001 --format json
|
||||
./gradlew check
|
||||
```
|
||||
|
||||
Add `--multiple` when a question permits several selections, and repeat `--choice`.
|
||||
`--text-file` accepts UTF-8 answers. `survey ask WRK-0001 SVY-0001` guides a human
|
||||
at a console; use `--input-file answers.txt` for explicit prepared input. Type option
|
||||
numbers separated by commas, or write a free-text answer (`text:` forces free text).
|
||||
Recommendations never count as answers. Revised answers signal review; they do not
|
||||
silently change accepted DECs or plans. Pending questions appear in next-actions.
|
||||
Tests generate JUnit results and JaCoCo coverage. Open
|
||||
`build/reports/jacoco/jacocoTestReport/html/index.html` for the coverage report.
|
||||
|
||||
## Exercise the agent contract
|
||||
- [Jenkins pipeline and setup](files/config/README.md): tests, coverage gates,
|
||||
report publication, and local Pipeline fixtures.
|
||||
- [GitHub Actions workflow](.github/workflows/build.yml): JVM verification and
|
||||
native build jobs.
|
||||
- [Native smoke script](scripts/native-smoke.sh): verification of a built executable
|
||||
in disposable projects.
|
||||
|
||||
The `fixture-general` and `fixture-reviewer` adapters perform predictable
|
||||
test transformations, with no model API or real semantic analysis. Use a disposable
|
||||
project to exercise the complete refinement flow:
|
||||
## Documentation
|
||||
|
||||
```sh
|
||||
mkdir aie-fixture
|
||||
cd aie-fixture
|
||||
aie init --name "Refinement fixture" --general-adapter fixture-general \
|
||||
--archive-policy reversible
|
||||
aie work create "Compare ideas"
|
||||
printf 'Rendering: measure layers\nInput: compare controls\n' > ideas.md
|
||||
aie agent run WRK-0001 --task-file ideas.md --request-id first-ideas
|
||||
aie survey ask WRK-0001 SVY-0001
|
||||
printf 'Synthetic observation for the contract test\n' > evidence.txt
|
||||
aie artifact add WRK-0001 --file evidence.txt --purpose "Explicit fixture evidence"
|
||||
aie agent configure --activity analyze --adapter fixture-reviewer
|
||||
aie agent run WRK-0001 --task "analyze: compare the fixture proposals" --request-id analysis
|
||||
aie agent run WRK-0001 --task "summarize current context"
|
||||
aie agent history WRK-0001 --format json
|
||||
aie work context WRK-0001
|
||||
aie project validate
|
||||
```
|
||||
| Guide | Contents |
|
||||
|---|---|
|
||||
| [Protocol reference](docs/protocol.md) | Commands, records, approval, persistence, and recovery |
|
||||
| [Compatibility](docs/compatibility.md) | Supported formats and update procedures |
|
||||
| [Discussion and refinement](docs/discussion-slice.md) | Topics, surveys, and proposal handling |
|
||||
| [Plan consolidation](docs/plan-consolidation.md) | Steps, results, and automatic completion |
|
||||
| [EPIC coordination](docs/epics.md) | Relationships and completion policies across Works |
|
||||
| [Local CLI adapters](docs/cli-adapters.md) | Provider setup and invocation contract |
|
||||
| [Architecture](docs/architecture.md) | Module boundaries and implementation design |
|
||||
| [Roadmap](docs/roadmap.md) | Implemented capabilities and planned work |
|
||||
| [Verification notes](docs/experiments.md) | Recorded experiments and validation results |
|
||||
|
||||
General handles activities without a configured specialization; specialized configuration
|
||||
wins. `--activity` selects explicitly. Fixture classification recognizes `analyze:` and
|
||||
`summarize`; otherwise refinement groups one idea per line, optionally `Topic: idea`.
|
||||
Profiles/models are fixture identifiers, not connections to an external provider.
|
||||
The analyze fixture reads stored answers/evidence, archives one proposal under the
|
||||
explicit policy and prepares another as a **draft** DEC. It never creates human approval.
|
||||
## Contributing
|
||||
|
||||
`discussion archive WRK DSC --reason TEXT --evidence ART` requires policy `reversible`
|
||||
and integrity-checked evidence; the default is `review-only`. `discussion restore`
|
||||
requires a reason and retains the source and disposition history. Run records retain
|
||||
requester, executor, source fingerprint, proposals and applied references. Identical
|
||||
completed request IDs reuse their result; changed input is rejected. Context marks
|
||||
older runs stale when sources change; summaries refresh only on an explicit new run.
|
||||
See [the refinement contract](docs/discussion-slice.md) for format and failure limits.
|
||||
Bug reports should include the AIE version, operating system, reproduction steps,
|
||||
and expected and actual behavior. For proposed changes, explain the problem and
|
||||
include relevant tests and documentation. Run `./gradlew check` before submitting
|
||||
a pull request.
|
||||
|
||||
## Connect local Codex and Claude CLIs
|
||||
Changes to persisted formats should preserve supported readers and historical
|
||||
fixtures. The [architecture](docs/architecture.md) and [compatibility guide](docs/compatibility.md)
|
||||
explain the existing contracts and how to evolve them.
|
||||
|
||||
`codex-cli` and `claude-cli` return typed Discussion/synthesis proposals that AIE
|
||||
validates before applying. Install/authenticate each provider's CLI separately;
|
||||
neither is required for ordinary AIE use or automated tests. AIE itself still needs
|
||||
no JVM or Node at runtime. Check the local interface without contacting a model:
|
||||
## License
|
||||
|
||||
```sh
|
||||
aie agent doctor --format json
|
||||
aie agent configure --adapter codex-cli --profile general --model default --timeout 120
|
||||
aie agent configure --activity analyze --adapter claude-cli --profile reviewer
|
||||
aie agent run WRK-0001 --activity summarize --task "Summarize the recorded goals and open questions"
|
||||
aie agent history WRK-0001 --format json
|
||||
```
|
||||
|
||||
Model `default` omits the provider model flag; explicit model names are passed as one
|
||||
argument. Profile is an AIE role instruction, not a vendor configuration file. General
|
||||
handles activities without a specialization; provider failure does not silently
|
||||
switch executors. Without `--activity`, general first classifies the request; ambiguous
|
||||
requests can yield a clarification survey. Previous RUN outputs travel with context
|
||||
as derived interpretations. They do not become verified evidence by being summarized.
|
||||
|
||||
Calls use stdin, fixed arguments, a private temporary directory, provider tool controls
|
||||
and timeout/output limits. Source repository working directories are not supplied.
|
||||
Credentials stay in provider stores/environment. RUN provenance records observed CLI
|
||||
version, configured role/model, duration and output digest; it does not claim an
|
||||
unreported actual model. Transport errors leave canonical Work data unchanged.
|
||||
For a nonstandard executable location, set `AIE_CODEX_EXECUTABLE` or
|
||||
`AIE_CLAUDE_EXECUTABLE` locally. No arbitrary extra-arguments option is supported.
|
||||
|
||||
Guided setup can collect general and activity-specific executors before writing files:
|
||||
|
||||
```sh
|
||||
aie init . --interactive
|
||||
# Or provide explicit prepared UTF-8 answers:
|
||||
aie init . --name "My Project" --interactive --input-file setup-answers.txt
|
||||
```
|
||||
|
||||
`init .` without --name starts guidance when a console is present. `init --name TEXT`
|
||||
stays noninteractive. No terminal/file or incomplete answers produces a diagnostic;
|
||||
setup never calls a model. See [the CLI adapter contract](docs/cli-adapters.md) for
|
||||
scope, supported controls, environment handling and actual validation results.
|
||||
|
||||
## Review, execute and close
|
||||
|
||||
Refine a draft with `decision update` (including `--text-file` for narrative), then
|
||||
record an actual human approval. The following fixture assumes the human has agreed:
|
||||
|
||||
```sh
|
||||
aie decision update WRK-0001 DEC-0001 \
|
||||
--context "Resume a small project change" --approach "One bounded slice" \
|
||||
--rationale "Keep the result verifiable" --by agent --reason "Discussion refined"
|
||||
aie decision accept WRK-0001 DEC-0001 \
|
||||
--by owner --reason "Explicitly agreed scope" --human-approved
|
||||
aie plan create WRK-0001 --title "Deliver the slice" --decision DEC-0001
|
||||
aie plan step add WRK-0001 PLN-0001 --title "Implement and test"
|
||||
# Execute the actual change/tests externally, then attach their observed result:
|
||||
aie artifact add WRK-0001 --file result.txt --purpose "Actual verification result"
|
||||
aie plan step status WRK-0001 PLN-0001 TSK-0001 COMPLETED \
|
||||
--by agent --reason "Recorded the observed test outcome" --evidence ART-0001
|
||||
# The last required step consolidates Plan and Work automatically.
|
||||
aie work check WRK-0001
|
||||
aie work reconcile WRK-0001 --requester agent --format json
|
||||
aie work archive WRK-0001 --by owner --reason "Delivery recorded"
|
||||
```
|
||||
|
||||
The framework consolidates completed Plans and their recorded results, without a
|
||||
model call or a new Work-level acceptance checklist. Unanswered questions/surveys,
|
||||
draft DECs and explicit blocking states remain pending. Empty sets never complete.
|
||||
`plan exclude WRK PLN [--step TSK] --by NAME --reason TEXT` reviews cancelled scope
|
||||
while retaining its history. See [the contract](docs/plan-consolidation.md).
|
||||
|
||||
Inspection-only Works without Plans retain human-reviewed `work complete`, with
|
||||
criterion evidence and `--integration PATH` or `--no-integration-needed "Reason"`.
|
||||
Human approval remains an explicit attestation for significant commitments; system
|
||||
completion is recorded separately and does not prove arbitrary prose semantically.
|
||||
|
||||
Plans are proportional: small Works need not have a DEC or plan. Plans can contain
|
||||
multiple steps, `--depends-on TSK-0001`, acceptance criteria and recorded results.
|
||||
Step execution requires completed dependencies and accepted referenced decisions;
|
||||
completed steps require evidence. `plan update`, `plan step update` and status changes
|
||||
allow explicit replanning. `decision reject` retains rejected proposals;
|
||||
`decision revise` creates a linked draft whose approval supersedes the prior decision.
|
||||
Use `decision history` / `plan history` to inspect snapshots and SHA-256 links.
|
||||
|
||||
Archived and terminal Works reject edits. Resume with
|
||||
`aie work reopen WRK-0001 --by owner --reason "New observation"`; previous completion
|
||||
records and all files remain. `status` hides archived Works unless `--all` is supplied.
|
||||
No housekeeping command deletes records or requires a Lesson document. Legacy agenda
|
||||
and Lesson import is deliberately deferred until this replacement is established.
|
||||
|
||||
## Coordinate an EPIC
|
||||
|
||||
An EPIC is a Work coordinating other Works in the same engineering project. Create
|
||||
each Work with its own scope/criteria and link it explicitly. All children are
|
||||
important by default; nested EPICs are allowed, with one parent per Work and no cycles.
|
||||
|
||||
```sh
|
||||
aie work create "Coordinate delivery" --acceptance "The reviewed child results satisfy the delivery"
|
||||
aie work create "First slice" --acceptance "First bounded result verified"
|
||||
aie work create "Second slice" --acceptance "Second bounded result verified"
|
||||
aie epic configure WRK-0001 --mode results --by agent --reason "Coordinate these slices"
|
||||
aie epic link WRK-0001 WRK-0002 --by agent --reason "First delivery"
|
||||
aie epic link WRK-0001 WRK-0003 --by agent --reason "Second delivery"
|
||||
# Only after actual human review of the policy and parent/child scopes:
|
||||
aie epic authorize WRK-0001 --by owner --reason "These results are sufficient for the parent criteria" --human-approved
|
||||
aie epic show WRK-0001 --format json
|
||||
aie epic check WRK-0001
|
||||
```
|
||||
|
||||
Children with Plans complete through deterministic Plan consolidation; inspection-only
|
||||
children can use human-reviewed `work complete`. Each
|
||||
lifecycle command checks affected ancestors and returns their status/pending results
|
||||
to the caller. Once important children and the parent's local checks pass, RESULTS
|
||||
auto-completes using an owned ART receipt. Its origin is SYSTEM_EPIC and
|
||||
humanApproved is false; the separate policy delegation remains explicit and traceable.
|
||||
No LLM performs the state checks, and arbitrary prose criteria are not semantically
|
||||
proved by the framework. `--requester` / `--request-id` correlate lifecycle reports.
|
||||
|
||||
An important cancelled child remains pending. Review a reduced scope with
|
||||
`epic importance EPIC CHILD --optional --by NAME --reason TEXT`, then authorize the
|
||||
revised policy explicitly. Optional children may remain open. Scope/link changes
|
||||
invalidate prior authority. An empty important set never auto-closes. Use mode
|
||||
`decomposition` when the parent delivers the decomposition itself: ordinary reviewed
|
||||
completion applies and does not wait for child execution.
|
||||
|
||||
Reopening an important child reopens RESULTS ancestors and retains prior delivery
|
||||
records. Optional changes do not invalidate them. Explicitly reopening an EPIC
|
||||
suspends its automatic authority so new children/scope can be planned. Inspect
|
||||
policy revisions with `epic history`; `epic reconcile [WRK]` recovers missed
|
||||
propagation from files and does not duplicate receipts/completions on repeated calls.
|
||||
See [the EPIC contract](docs/epics.md) for recovery and publication limits.
|
||||
|
||||
## Refine a Work
|
||||
|
||||
Update agreed scope without editing YAML manually:
|
||||
|
||||
```sh
|
||||
ai-engineering work update WRK-0001 \
|
||||
--goal "Define and validate the next small slice" \
|
||||
--description "Scope refined during discussion" \
|
||||
--motivation "Continue from recorded evidence" \
|
||||
--constraint "Preserve existing source behavior" \
|
||||
--constraint "Use isolated test data" \
|
||||
--acceptance "A fresh execution reconstructs the context" \
|
||||
--format json
|
||||
```
|
||||
|
||||
Only supplied fields change. `--title` is also available; changing it preserves the
|
||||
Work ID and folder. Status, creator, creation time, repository snapshots and all
|
||||
discussion/decision/artifact references are retained. Identical updates do not rewrite
|
||||
the file or change its modification timestamp. `work status` remains the lifecycle
|
||||
command; updating scope does not approve a decision.
|
||||
|
||||
**List options replace the whole corresponding list.** Repeat `--constraint` or
|
||||
`--acceptance` for every value to retain. Omitted lists are preserved. Clear them
|
||||
explicitly with `--clear-constraints` or `--clear-acceptance`; a clear option cannot be
|
||||
combined with values for the same list. Empty description/motivation strings clear
|
||||
those fields; title, goal and individual list values must be nonblank.
|
||||
|
||||
For longer discussion entries, write a Markdown draft and import it:
|
||||
|
||||
```sh
|
||||
ai-engineering discussion add WRK-0001 \
|
||||
--kind SUGGESTION --author agent \
|
||||
--text-file ./proposal.md
|
||||
```
|
||||
|
||||
Choose exactly one of `--text` and `--text-file`. File paths resolve from the invocation
|
||||
directory, including when `--project` points elsewhere. Files must contain nonblank
|
||||
UTF-8 text and be at most 1 MiB. The complete content, including line endings and
|
||||
Markdown, becomes discussion text; source front matter is not interpreted. The
|
||||
source is read once and left unchanged. Use `artifact add` separately for evidence.
|
||||
|
||||
## Multiple repositories in one project
|
||||
|
||||
From an external project directory with existing `runtime/` and `studio/` Git
|
||||
repositories, run:
|
||||
|
||||
```sh
|
||||
ai-engineering init --name "Prometeu"
|
||||
ai-engineering repo add runtime --path runtime --language rust
|
||||
ai-engineering repo add studio --path studio --language java
|
||||
ai-engineering repo list --format json
|
||||
ai-engineering work create "Improve scene editor" \
|
||||
--repo runtime --repo studio \
|
||||
--goal "Evaluate portable scene rendering" \
|
||||
--constraint "No external service" \
|
||||
--acceptance "A fresh execution reconstructs the context"
|
||||
ai-engineering discussion add WRK-0001 --kind QUESTION \
|
||||
--text "Should we use layered Canvas?"
|
||||
ai-engineering discussion add WRK-0001 --kind RESPONSE --responds-to DSC-0001 \
|
||||
--text "Run a rendering experiment first"
|
||||
ai-engineering artifact add WRK-0001 --file result.txt \
|
||||
--purpose "Rendering measurements" --origin "manual experiment"
|
||||
ai-engineering decision draft WRK-0001 --title "Evaluate layered Canvas" \
|
||||
--context "Scene editor rendering" --approach "Prototype layers" \
|
||||
--rationale "Measure before committing" --evidence ART-0001
|
||||
ai-engineering work context WRK-0001 --format markdown
|
||||
ai-engineering work context WRK-0001 --format json
|
||||
ai-engineering project validate
|
||||
```
|
||||
|
||||
The CLI never initializes or modifies Git repositories. To register an existing
|
||||
submodule use `--type git-submodule`; the default is `linked-git`. Repositories are
|
||||
read-only unless registration explicitly includes `--allow-edit`. This is policy
|
||||
metadata; it does not replace an operating-system sandbox. No source edits or
|
||||
configured validation commands are executed in these milestones.
|
||||
|
||||
`--project /path/to/project` works before or after subcommands. Otherwise discovery
|
||||
searches upward, including when invoked inside a nested source directory.
|
||||
Work IDs use uppercase hexadecimal with at least four digits:
|
||||
`WRK-0009`, `WRK-000A`, …, `WRK-000F`, `WRK-0010`. Existing IDs retain their spelling;
|
||||
legacy counters are upgraded when the next Work is created, without reusing reserved
|
||||
IDs. Child IDs remain decimal and are scoped to their Work. New discussions can
|
||||
be grouped with `--discussion <name>`. History remains append-only. `work status
|
||||
WRK-0001 ACTIVE` changes an open Work's lifecycle status. Completion uses
|
||||
Plan consolidation or human-reviewed `work complete` for inspection-only Works;
|
||||
terminal Works return to ACTIVE through `work reopen`.
|
||||
Every command provides `--help`; inspection commands support `--format json`.
|
||||
|
||||
New discussion files keep metadata in YAML front matter (`documentVersion: 2`) and
|
||||
the complete text in the Markdown body. Headings, lists, tables and code blocks remain
|
||||
readable directly in an editor. Markdown context/list output also displays prose
|
||||
directly; JSON continues to expose the same `text` field.
|
||||
|
||||
Older discussion files with `text` in YAML are read without being rewritten. To
|
||||
convert a Work's existing discussions explicitly with the updated CLI:
|
||||
|
||||
```sh
|
||||
ai-engineering discussion migrate WRK-0001
|
||||
```
|
||||
|
||||
Originals are backed up under `.ai-engineering/.local/backups/discussions/`; the
|
||||
command reports the backup paths. IDs, authors, dates, text, Work metadata and exported
|
||||
context data are preserved. Running the command again skips converted files. Migration
|
||||
refuses legacy trailing notes rather than silently dropping them. Use the updated CLI
|
||||
for files in document version 2; old CLI builds cannot read that new file format.
|
||||
|
||||
Exit codes: **0** success, **1** unexpected I/O/runtime failure, **2** invalid input
|
||||
or unsafe path, **3** missing project/resource, **4** structural validation failure.
|
||||
Validation commands return 4 with diagnostics even when the underlying issue is a
|
||||
missing referenced resource or unsafe persisted path.
|
||||
|
||||
## Architecture and protocol
|
||||
|
||||
One Gradle project, one Spring Boot application, ten verified Modulith modules:
|
||||
project, work, discussion, decision, planning, artifact, agent, verification, CLI and shared filesystem
|
||||
infrastructure. Domain state is immutable Java records; persistence uses versioned
|
||||
YAML and Markdown front matter. Files remain understandable without this CLI.
|
||||
|
||||
- [Architecture and reuse decisions](docs/architecture.md)
|
||||
- [Protocol schema and persistence guarantees](docs/protocol.md)
|
||||
- [Roadmap and acceptance criteria](docs/roadmap.md)
|
||||
- [Experiments and actual validation results](docs/experiments.md)
|
||||
|
||||
No Agenda, Lesson or autonomous OODA engine is part of this implementation. Local
|
||||
Codex/Claude integrations are limited to proposals; EPIC/conformance/state checks
|
||||
run in framework code. The two fixture adapters remain available for offline use.
|
||||
Licensed under the [MIT License](LICENSE).
|
||||
|
||||
+6
-2
@@ -10,6 +10,10 @@ plugins {
|
||||
group = "net.intrepid"
|
||||
version = "0.1.0"
|
||||
|
||||
tasks.withType<Jar>().configureEach {
|
||||
from("LICENSE") { into("META-INF") }
|
||||
}
|
||||
|
||||
java { toolchain { languageVersion = JavaLanguageVersion.of(25) } }
|
||||
repositories { mavenCentral() }
|
||||
dependencies {
|
||||
@@ -78,7 +82,7 @@ tasks.register<Zip>("nativeDistZip") {
|
||||
include("ai-engineering", "ai-engineering.exe")
|
||||
filePermissions { unix("rwxr-xr-x") }
|
||||
}
|
||||
from("README.md")
|
||||
from("README.md", "LICENSE")
|
||||
from("docs") { into("docs") }
|
||||
}
|
||||
tasks.register<Tar>("nativeDistTar") {
|
||||
@@ -89,6 +93,6 @@ tasks.register<Tar>("nativeDistTar") {
|
||||
compression = Compression.GZIP
|
||||
destinationDirectory = layout.buildDirectory.dir("distributions")
|
||||
from(layout.buildDirectory.dir("native/nativeCompile")) { include("ai-engineering"); filePermissions { unix("rwxr-xr-x") } }
|
||||
from("README.md")
|
||||
from("README.md", "LICENSE")
|
||||
from("docs") { into("docs") }
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user