docs: prepare public README and distribute MIT license
This commit is contained in:
@@ -1,3 +1,3 @@
|
|||||||
---
|
---
|
||||||
schemaVersion: 2
|
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
|
[MIT License](LICENSE) · [Quick start](#quick-start) · [Documentation](#documentation) · [Contributing](#contributing)
|
||||||
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.
|
|
||||||
|
|
||||||
Milestones 0 and 1 and the operational replacement baseline are implemented.
|
AI Engineering (AIE) is a local CLI for keeping engineering work understandable
|
||||||
Discussion refinement now includes topics, surveys and two deterministic adapters
|
across people, AI agents, and sessions. It stores goals, discussions, decisions,
|
||||||
to verify the integration contract. Local Codex/Claude adapters now exercise that
|
plans, and verification evidence as readable files alongside your project.
|
||||||
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.
|
|
||||||
|
|
||||||
## 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),
|
## What you can do
|
||||||
and internet access for the first dependency download. The Gradle Wrapper is included.
|
|
||||||
|
|
||||||
The recommended local toolchain is GraalVM Community Edition, pinned in `.sdkmanrc`.
|
- **Preserve context:** resume a Work from recorded goals, discussion, decisions,
|
||||||
With SDKMAN installed, activate it from the project root:
|
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
|
```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
|
./gradlew bootJar
|
||||||
java -jar build/libs/ai-engineering-0.1.0.jar --help
|
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,
|
For the examples below, you can define a command in your current POSIX shell.
|
||||||
Gradle 9.3.1, Picocli 4.7.7, Native Build Tools 0.11.5, JUnit 5.13.4.
|
Run this from the repository root so the JAR path stays valid after changing folders:
|
||||||
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.
|
|
||||||
|
|
||||||
```sh
|
```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
|
./gradlew nativeCompile
|
||||||
./build/native/nativeCompile/ai-engineering --help
|
./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>.*`.
|
Add the executable's directory to `PATH` to use `ai-engineering` from other folders.
|
||||||
Build each binary on its target OS/architecture; Native Image is not a general cross
|
On Windows the executable is named `ai-engineering.exe`. The shorter `aie` command
|
||||||
compiler. CI defines Linux x86_64, macOS ARM64 and Windows x86_64 native builds.
|
can be provided as a local alias or symlink.
|
||||||
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).
|
|
||||||
|
|
||||||
## Jenkins tests and coverage
|
To create distribution archives:
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
./gradlew test jacocoTestReport jenkinsPipelineTest --continue --console=plain
|
./gradlew nativeDistZip nativeDistTar
|
||||||
```
|
```
|
||||||
|
|
||||||
Coverage HTML is generated at
|
Archives are written to `build/distributions/` and include the README, documentation,
|
||||||
`build/reports/jacoco/jacocoTestReport/html/index.html`. See the
|
and MIT license. Build on the intended OS and architecture; the native CI matrix
|
||||||
[Jenkins setup and verification guide](files/config/README.md) for required plugins,
|
is defined in [.github/workflows/build.yml](.github/workflows/build.yml).
|
||||||
thresholds, report paths and the boundary between local checks and a controller run.
|
|
||||||
|
|
||||||
## 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
|
```sh
|
||||||
ai-engineering init --name "My Application"
|
mkdir my-project
|
||||||
ai-engineering work create "Improve the application" \
|
cd my-project
|
||||||
--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 init --name "My Project"
|
||||||
ai-engineering decision draft WRK-0001 --title "Evaluate the proposed approach"
|
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 work context WRK-0001 --format markdown
|
||||||
ai-engineering project validate
|
ai-engineering project validate
|
||||||
```
|
```
|
||||||
|
|
||||||
This creates `.ai-engineering/` beside your existing source files. A project with
|
`init` creates `.ai-engineering/` and installs portable instructions for agents,
|
||||||
`repositories: []` is fully supported; the workflow above does not require Git to be
|
including a managed block in the project's `AGENTS.md`. Existing project rules
|
||||||
installed. Its Works have no Git revision snapshots. Git becomes relevant when you
|
outside that block are preserved. Keep the canonical engineering files under
|
||||||
choose to register repositories.
|
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
|
```sh
|
||||||
ai-engineering repo add app --path .
|
ai-engineering repo add api --path api --language java
|
||||||
ai-engineering work create "Investigate a change" --repo app
|
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
|
For a project whose root is itself a Git repository, use `repo add app --path .`.
|
||||||
`zelda-1/` project can keep `.ai-engineering/` directly inside `zelda-1/`, without
|
Registration defaults to read-only access and does not change Git configuration.
|
||||||
registering the separate runtime or editor repositories. Each Work explicitly selects
|
Each Work selects its repositories with `--repo`; registration is optional for
|
||||||
any registered repositories it needs with `--repo`.
|
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
|
| Record | Purpose |
|
||||||
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
|
| Work | Goal, constraints, acceptance criteria, and lifecycle |
|
||||||
block. Changed instruction files are backed up under `.local/backups/onboarding/`.
|
| Discussion | Observations, questions, proposals, and conclusions |
|
||||||
For an existing project, install the entry contract explicitly:
|
| 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
|
```sh
|
||||||
aie onboard
|
ai-engineering agent doctor --format json
|
||||||
aie status --format json
|
ai-engineering agent configure --adapter codex-cli --profile general --model default
|
||||||
aie next-actions --format json
|
ai-engineering agent configure --activity analyze --adapter claude-cli --profile reviewer
|
||||||
aie work context WRK-0001
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Use `ai-engineering` if the optional `aie` alias is unavailable. `onboard` is
|
Adapters produce proposals and summaries that AIE validates before applying.
|
||||||
idempotent; it leaves Work records unchanged. `aie guide` reads the bundled guide
|
Provider authentication remains with the provider's CLI. Offline fixture adapters
|
||||||
even outside a project; `aie guide --format json` shows the discovery manifest.
|
are available for deterministic tests. See the [local CLI adapter guide](docs/cli-adapters.md)
|
||||||
An agent that finds `.ai-engineering` can read its README and manifest directly.
|
for setup, invocation controls, provenance, and supported behavior.
|
||||||
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.
|
|
||||||
|
|
||||||
## Inspect compatibility before updating
|
## Compatibility and updates
|
||||||
|
|
||||||
|
Inspect a project before considering a format update:
|
||||||
|
|
||||||
```sh
|
```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
|
`CURRENT` and `LEGACY_COMPATIBLE` both indicate readable formats. Supported older
|
||||||
CLI release, protocol contract revision and actual storage formats, including record
|
records remain readable without automatic normalization or reopening completed
|
||||||
history. `CURRENT` and `LEGACY_COMPATIBLE` both mean readable; neither requires a
|
Works. `onboard` refreshes entry instructions with backups while preserving Work
|
||||||
migration. `UNSUPPORTED` and `INVALID` return exit 4 and identify affected files.
|
files. The [compatibility guide](docs/compatibility.md) explains contract versions,
|
||||||
Validation of references and evidence remains `aie project validate`.
|
storage formats, diagnostics, and future explicit migrations.
|
||||||
|
|
||||||
Keep completed Works in their existing formats. Older supported files are interpreted
|
## Development and verification
|
||||||
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.
|
|
||||||
|
|
||||||
## Discuss topics and answer surveys
|
The test suite requires JDK 25 and Git. Run the project checks with:
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
aie topic create WRK-0001 "Rendering"
|
./gradlew check
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Add `--multiple` when a question permits several selections, and repeat `--choice`.
|
Tests generate JUnit results and JaCoCo coverage. Open
|
||||||
`--text-file` accepts UTF-8 answers. `survey ask WRK-0001 SVY-0001` guides a human
|
`build/reports/jacoco/jacocoTestReport/html/index.html` for the coverage report.
|
||||||
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.
|
|
||||||
|
|
||||||
## 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
|
## Documentation
|
||||||
test transformations, with no model API or real semantic analysis. Use a disposable
|
|
||||||
project to exercise the complete refinement flow:
|
|
||||||
|
|
||||||
```sh
|
| Guide | Contents |
|
||||||
mkdir aie-fixture
|
|---|---|
|
||||||
cd aie-fixture
|
| [Protocol reference](docs/protocol.md) | Commands, records, approval, persistence, and recovery |
|
||||||
aie init --name "Refinement fixture" --general-adapter fixture-general \
|
| [Compatibility](docs/compatibility.md) | Supported formats and update procedures |
|
||||||
--archive-policy reversible
|
| [Discussion and refinement](docs/discussion-slice.md) | Topics, surveys, and proposal handling |
|
||||||
aie work create "Compare ideas"
|
| [Plan consolidation](docs/plan-consolidation.md) | Steps, results, and automatic completion |
|
||||||
printf 'Rendering: measure layers\nInput: compare controls\n' > ideas.md
|
| [EPIC coordination](docs/epics.md) | Relationships and completion policies across Works |
|
||||||
aie agent run WRK-0001 --task-file ideas.md --request-id first-ideas
|
| [Local CLI adapters](docs/cli-adapters.md) | Provider setup and invocation contract |
|
||||||
aie survey ask WRK-0001 SVY-0001
|
| [Architecture](docs/architecture.md) | Module boundaries and implementation design |
|
||||||
printf 'Synthetic observation for the contract test\n' > evidence.txt
|
| [Roadmap](docs/roadmap.md) | Implemented capabilities and planned work |
|
||||||
aie artifact add WRK-0001 --file evidence.txt --purpose "Explicit fixture evidence"
|
| [Verification notes](docs/experiments.md) | Recorded experiments and validation results |
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
||||||
General handles activities without a configured specialization; specialized configuration
|
## Contributing
|
||||||
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.
|
|
||||||
|
|
||||||
`discussion archive WRK DSC --reason TEXT --evidence ART` requires policy `reversible`
|
Bug reports should include the AIE version, operating system, reproduction steps,
|
||||||
and integrity-checked evidence; the default is `review-only`. `discussion restore`
|
and expected and actual behavior. For proposed changes, explain the problem and
|
||||||
requires a reason and retains the source and disposition history. Run records retain
|
include relevant tests and documentation. Run `./gradlew check` before submitting
|
||||||
requester, executor, source fingerprint, proposals and applied references. Identical
|
a pull request.
|
||||||
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.
|
|
||||||
|
|
||||||
## 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
|
## License
|
||||||
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:
|
|
||||||
|
|
||||||
```sh
|
Licensed under the [MIT License](LICENSE).
|
||||||
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.
|
|
||||||
|
|||||||
+6
-2
@@ -10,6 +10,10 @@ plugins {
|
|||||||
group = "net.intrepid"
|
group = "net.intrepid"
|
||||||
version = "0.1.0"
|
version = "0.1.0"
|
||||||
|
|
||||||
|
tasks.withType<Jar>().configureEach {
|
||||||
|
from("LICENSE") { into("META-INF") }
|
||||||
|
}
|
||||||
|
|
||||||
java { toolchain { languageVersion = JavaLanguageVersion.of(25) } }
|
java { toolchain { languageVersion = JavaLanguageVersion.of(25) } }
|
||||||
repositories { mavenCentral() }
|
repositories { mavenCentral() }
|
||||||
dependencies {
|
dependencies {
|
||||||
@@ -78,7 +82,7 @@ tasks.register<Zip>("nativeDistZip") {
|
|||||||
include("ai-engineering", "ai-engineering.exe")
|
include("ai-engineering", "ai-engineering.exe")
|
||||||
filePermissions { unix("rwxr-xr-x") }
|
filePermissions { unix("rwxr-xr-x") }
|
||||||
}
|
}
|
||||||
from("README.md")
|
from("README.md", "LICENSE")
|
||||||
from("docs") { into("docs") }
|
from("docs") { into("docs") }
|
||||||
}
|
}
|
||||||
tasks.register<Tar>("nativeDistTar") {
|
tasks.register<Tar>("nativeDistTar") {
|
||||||
@@ -89,6 +93,6 @@ tasks.register<Tar>("nativeDistTar") {
|
|||||||
compression = Compression.GZIP
|
compression = Compression.GZIP
|
||||||
destinationDirectory = layout.buildDirectory.dir("distributions")
|
destinationDirectory = layout.buildDirectory.dir("distributions")
|
||||||
from(layout.buildDirectory.dir("native/nativeCompile")) { include("ai-engineering"); filePermissions { unix("rwxr-xr-x") } }
|
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") }
|
from("docs") { into("docs") }
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user