docs: prepare public README and distribute MIT license

This commit is contained in:
2026-11-16 10:54:46 +00:00
parent a232cc144b
commit 8572f43149
26 changed files with 826 additions and 434 deletions
+1 -1
View File
@@ -1,3 +1,3 @@
--- ---
schemaVersion: 2 schemaVersion: 2
lastWork: "0004" lastWork: "0006"
@@ -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"
@@ -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.
@@ -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"
@@ -0,0 +1,10 @@
{
"schemaVersion" : 1,
"workId" : "WRK-0005",
"inputHash" : "93311e3a086147c0f89260e689c7a898c1d53d570dfe3c84cf5e18441f72cb19",
"plans" : [ {
"id" : "PLN-0001",
"revision" : 4,
"sha256" : "06fa822257b8e28bde476f039662eb4e0fd03b6e386cae2341f54e12809772e4"
} ]
}
@@ -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
---
@@ -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
---
@@ -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
---
@@ -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
---
@@ -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"
@@ -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
@@ -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"
@@ -0,0 +1,10 @@
{
"schemaVersion" : 1,
"workId" : "WRK-0006",
"inputHash" : "a0f9e8fe82ef06b289a0a825802a7f6d4fab02d3f1788831f1d7a18991f61b3e",
"plans" : [ {
"id" : "PLN-0001",
"revision" : 7,
"sha256" : "a177b558f456203fcb509c245289441056b4a6e8e1857dcff38bb59e0f96864b"
} ]
}
@@ -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.
@@ -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
---
@@ -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
---
@@ -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
---
@@ -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
---
@@ -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
---
@@ -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
---
@@ -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
---
+21
View File
@@ -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.
+170 -431
View File
@@ -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
View File
@@ -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") }
} }