From 95c28e2e792762990af3bba377327d9472a63e96 Mon Sep 17 00:00:00 2001 From: Nilton Constantino Date: Mon, 16 Nov 2026 10:54:46 +0000 Subject: [PATCH] docs: prepare public README and distribute MIT license --- .ai-engineering/works/.sequence.yaml | 2 +- .../artifacts/evidence/ART-0001/artifact.yaml | 11 + .../artifacts/evidence/ART-0001/payload | 1 + .../artifacts/evidence/ART-0002/artifact.yaml | 12 + .../artifacts/evidence/ART-0002/payload | 10 + .../plans/.history/PLN-0001/r0001.md | 18 + .../plans/.history/PLN-0001/r0002.md | 28 + .../plans/.history/PLN-0001/r0003.md | 29 + .../plans/PLN-0001.md | 29 + .../work.md | 61 ++ .../artifacts/evidence/ART-0001/artifact.yaml | 11 + .../artifacts/evidence/ART-0001/payload | 48 ++ .../artifacts/evidence/ART-0002/artifact.yaml | 12 + .../artifacts/evidence/ART-0002/payload | 10 + .../discussions/DSC-0001.md | 13 + .../plans/.history/PLN-0001/r0001.md | 18 + .../plans/.history/PLN-0001/r0002.md | 29 + .../plans/.history/PLN-0001/r0003.md | 41 ++ .../plans/.history/PLN-0001/r0004.md | 41 ++ .../plans/.history/PLN-0001/r0005.md | 44 ++ .../plans/.history/PLN-0001/r0006.md | 46 ++ .../plans/PLN-0001.md | 45 ++ .../work.md | 71 +++ LICENSE | 21 + README.md | 601 +++++------------- build.gradle.kts | 8 +- 26 files changed, 826 insertions(+), 434 deletions(-) create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/artifact.yaml create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/payload create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/artifact.yaml create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/payload create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0001.md create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0002.md create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0003.md create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/PLN-0001.md create mode 100644 .ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/work.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/artifact.yaml create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/payload create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/artifact.yaml create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/payload create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/discussions/DSC-0001.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0001.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0002.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0003.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0004.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0005.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0006.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/PLN-0001.md create mode 100644 .ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/work.md create mode 100644 LICENSE diff --git a/.ai-engineering/works/.sequence.yaml b/.ai-engineering/works/.sequence.yaml index b5389cb..a8e4683 100644 --- a/.ai-engineering/works/.sequence.yaml +++ b/.ai-engineering/works/.sequence.yaml @@ -1,3 +1,3 @@ --- schemaVersion: 2 -lastWork: "0004" +lastWork: "0006" diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/artifact.yaml b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/artifact.yaml new file mode 100644 index 0000000..c8924bf --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/artifact.yaml @@ -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" diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/payload b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/payload new file mode 100644 index 0000000..457474c --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0001/payload @@ -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. diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/artifact.yaml b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/artifact.yaml new file mode 100644 index 0000000..2705c23 --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/artifact.yaml @@ -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" diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/payload b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/payload new file mode 100644 index 0000000..9eb4749 --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/artifacts/evidence/ART-0002/payload @@ -0,0 +1,10 @@ +{ + "schemaVersion" : 1, + "workId" : "WRK-0005", + "inputHash" : "93311e3a086147c0f89260e689c7a898c1d53d570dfe3c84cf5e18441f72cb19", + "plans" : [ { + "id" : "PLN-0001", + "revision" : 4, + "sha256" : "06fa822257b8e28bde476f039662eb4e0fd03b6e386cae2341f54e12809772e4" + } ] +} diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0001.md b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0001.md new file mode 100644 index 0000000..ef35725 --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0001.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0002.md b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0002.md new file mode 100644 index 0000000..62b479b --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0002.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0003.md b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0003.md new file mode 100644 index 0000000..296bca2 --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/.history/PLN-0001/r0003.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/PLN-0001.md b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/PLN-0001.md new file mode 100644 index 0000000..b074a29 --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/plans/PLN-0001.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/work.md b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/work.md new file mode 100644 index 0000000..cd9febd --- /dev/null +++ b/.ai-engineering/works/WRK-0005-remover-referencia-ao-piloto-do-readme/work.md @@ -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 +--- diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/artifact.yaml b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/artifact.yaml new file mode 100644 index 0000000..699ecab --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/artifact.yaml @@ -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" diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/payload b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/payload new file mode 100644 index 0000000..439f4a1 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0001/payload @@ -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 diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/artifact.yaml b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/artifact.yaml new file mode 100644 index 0000000..109fe1a --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/artifact.yaml @@ -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" diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/payload b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/payload new file mode 100644 index 0000000..40b57e7 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/artifacts/evidence/ART-0002/payload @@ -0,0 +1,10 @@ +{ + "schemaVersion" : 1, + "workId" : "WRK-0006", + "inputHash" : "a0f9e8fe82ef06b289a0a825802a7f6d4fab02d3f1788831f1d7a18991f61b3e", + "plans" : [ { + "id" : "PLN-0001", + "revision" : 7, + "sha256" : "a177b558f456203fcb509c245289441056b4a6e8e1857dcff38bb59e0f96864b" + } ] +} diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/discussions/DSC-0001.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/discussions/DSC-0001.md new file mode 100644 index 0000000..10bc9f5 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/discussions/DSC-0001.md @@ -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. \ No newline at end of file diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0001.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0001.md new file mode 100644 index 0000000..5b7b733 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0001.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0002.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0002.md new file mode 100644 index 0000000..145d7c1 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0002.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0003.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0003.md new file mode 100644 index 0000000..e9c5e95 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0003.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0004.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0004.md new file mode 100644 index 0000000..45afc77 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0004.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0005.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0005.md new file mode 100644 index 0000000..2e37d7d --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0005.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0006.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0006.md new file mode 100644 index 0000000..a857d0f --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/.history/PLN-0001/r0006.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/PLN-0001.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/PLN-0001.md new file mode 100644 index 0000000..1f21bf1 --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/plans/PLN-0001.md @@ -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 +--- + diff --git a/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/work.md b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/work.md new file mode 100644 index 0000000..08a383e --- /dev/null +++ b/.ai-engineering/works/WRK-0006-preparar-readme-publico-e-licenca-mit/work.md @@ -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 +--- diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..14c3639 --- /dev/null +++ b/LICENSE @@ -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. diff --git a/README.md b/README.md index 61df6b2..d19a352 100644 --- a/README.md +++ b/README.md @@ -1,491 +1,230 @@ -# ai-engineering +# AI Engineering -An open, agent-agnostic engineering protocol and CLI for simple projects and projects -spanning multiple repositories. Git is optional. Works belong to the engineering -project. Canonical files preserve goals, discussion, -decisions, plans and evidence so another person or agent can continue without chat history. +[MIT License](LICENSE) · [Quick start](#quick-start) · [Documentation](#documentation) · [Contributing](#contributing) -Milestones 0 and 1 and the operational replacement baseline are implemented. -Discussion refinement now includes topics, surveys and two deterministic adapters -to verify the integration contract. Local Codex/Claude adapters now exercise that -contract with real providers for proposals and synthesis. -The application runs locally in non-web mode; -it needs no model API, database or running service. +AI Engineering (AIE) is a local CLI for keeping engineering work understandable +across people, AI agents, and sessions. It stores goals, discussions, decisions, +plans, and verification evidence as readable files alongside your project. -## Build and run +Use it in a single folder or across several source repositories. Git is optional. +The core workflow runs without a model API, database, or background service. -Build requirements: JDK 25, Git (for repository inspection and integration fixtures), -and internet access for the first dependency download. The Gradle Wrapper is included. +## What you can do -The recommended local toolchain is GraalVM Community Edition, pinned in `.sdkmanrc`. -With SDKMAN installed, activate it from the project root: +- **Preserve context:** resume a Work from recorded goals, discussion, decisions, + and evidence instead of relying on chat history. +- **Refine ideas:** organize topics, collect answers through surveys, and retain + the history when an answer or decision changes. +- **Track delivery:** connect plans, dependencies, observed results, and evidence; + consolidate completed plans through deterministic checks. +- **Coordinate repositories:** explicitly select the repositories involved in each + Work, while keeping engineering records in one project. +- **Work with AI agents:** provide portable entry instructions and structured + context; optionally use local Codex or Claude CLIs for proposals and summaries. +- **Retain history:** read supported older formats without rewriting completed + Works, approvals, or evidence. + +A **Work** is the unit of engineering activity: a scoped problem or change with +its own context and history. Decisions and plans are added when the work needs them. +AIE records the work and checks its structure; people and agents choose solutions, +change source code, run tests, and assess the results. + +## Installation + +### Run from source + +Clone this repository and open its root directory. Building the JVM application +requires **JDK 25** and access to dependency repositories on the first build. +The Gradle Wrapper is included; a separate Gradle installation is unnecessary. ```sh -sdk env install # only needed if the pinned JDK is not installed -sdk env -export GRAALVM_HOME="$JAVA_HOME" -java --version -native-image --version -``` - -SDKMAN candidate `25.5.5.0+3-graalce` provides GraalVM CE 25.5.5.0.3 based on -JDK 25.0.5.0.3. The Java language/bytecode target remains 25. SDKMAN is optional; -setting `JAVA_HOME` and `GRAALVM_HOME` to an equivalent GraalVM installation also works. - -```sh -./gradlew clean test ./gradlew bootJar java -jar build/libs/ai-engineering-0.1.0.jar --help -java -jar build/libs/ai-engineering-0.1.0.jar --version ``` -Pinned stack: Java target 25, Spring Boot 4.0.9, Spring Modulith 2.0.9, -Gradle 9.3.1, Picocli 4.7.7, Native Build Tools 0.11.5, JUnit 5.13.4. -Jackson YAML/JSON and AssertJ versions come from the pinned Spring Boot BOM. -Compatibility sources and rationale are in [architecture](docs/architecture.md). - -## Native installation and packaging - -A native distribution contains `ai-engineering` (`ai-engineering.exe` on Windows). -Extract the platform archive and put that executable on `PATH`. Running it requires -no JVM. Git must be on `PATH` for commands that inspect registered repositories. -There are no published release downloads yet; packaging tasks create local archives. - -Building requires GraalVM for **JDK 25**, Native Image and the host C/C++ toolchain: -Xcode Command Line Tools on macOS, GCC and development libraries on Linux, or the -Visual Studio C++ build tools on Windows. Set `JAVA_HOME` and `GRAALVM_HOME` to the -GraalVM JDK home (`Contents/Home` on macOS). -When SDKMAN's `current` points to another JDK, set both variables explicitly; -Gradle's `org.gradle.java.home` alone does not select the Native Image tool. +For the examples below, you can define a command in your current POSIX shell. +Run this from the repository root so the JAR path stays valid after changing folders: ```sh +export AIE_JAR="$PWD/build/libs/ai-engineering-0.1.0.jar" +ai-engineering() { java -jar "$AIE_JAR" "$@"; } +``` + +The JAR requires Java 25 at runtime. On Windows, use `gradlew.bat` in place of +`./gradlew`; you can invoke the JAR directly with `java -jar` and its full path. + +### Build a native executable + +The native executable runs without a JVM. Building it requires **GraalVM for +JDK 25**, Native Image, and a C/C++ toolchain for the target platform. Set both +`JAVA_HOME` and `GRAALVM_HOME` to your GraalVM installation. + +If you use SDKMAN, the repository pins a compatible toolchain in [.sdkmanrc](.sdkmanrc): + +```sh +sdk env install +sdk env +export GRAALVM_HOME="$JAVA_HOME" ./gradlew nativeCompile ./build/native/nativeCompile/ai-engineering --help -./gradlew nativeDistZip nativeDistTar -PtargetPlatform=macos-arm64 -bash scripts/native-smoke.sh "$PWD/build/native/nativeCompile/ai-engineering" ``` -Archives are written to `build/distributions/ai-engineering-0.1.0-.*`. -Build each binary on its target OS/architecture; Native Image is not a general cross -compiler. CI defines Linux x86_64, macOS ARM64 and Windows x86_64 native builds. -macOS x86_64 remains a target with an upstream toolchain availability limitation: -GraalVM 25 dropped that port; see [roadmap](docs/roadmap.md). Local verification -results, including which native binaries were actually tested, are in [experiments](docs/experiments.md). +Add the executable's directory to `PATH` to use `ai-engineering` from other folders. +On Windows the executable is named `ai-engineering.exe`. The shorter `aie` command +can be provided as a local alias or symlink. -## Jenkins tests and coverage - -The Jenkins pipeline is [files/config/Jenkinsfile](files/config/Jenkinsfile). Configure -that Script Path in a Pipeline from SCM job on a Unix agent with JDK 25 and Git. -It runs tests with JaCoCo and publishes JUnit, coverage XML/HTML and raw execution -data, including available diagnostics after failures. Coverage gates follow Studio. +To create distribution archives: ```sh -./gradlew test jacocoTestReport jenkinsPipelineTest --continue --console=plain +./gradlew nativeDistZip nativeDistTar ``` -Coverage HTML is generated at -`build/reports/jacoco/jacocoTestReport/html/index.html`. See the -[Jenkins setup and verification guide](files/config/README.md) for required plugins, -thresholds, report paths and the boundary between local checks and a controller run. +Archives are written to `build/distributions/` and include the README, documentation, +and MIT license. Build on the intended OS and architecture; the native CI matrix +is defined in [.github/workflows/build.yml](.github/workflows/build.yml). -## Start in a simple project +## Quick start -Run inside the folder you already use for your application, game or library: +With the CLI available, create an engineering workspace in a new folder: ```sh -ai-engineering init --name "My Application" -ai-engineering work create "Improve the application" \ - --goal "Preserve enough context to continue in another session" -ai-engineering discussion add WRK-0001 --text "Record the current state and next questions." -ai-engineering decision draft WRK-0001 --title "Evaluate the proposed approach" +mkdir my-project +cd my-project + +ai-engineering init --name "My Project" +ai-engineering work create "Improve configuration errors" \ + --goal "Make invalid configuration easier to diagnose" \ + --acceptance "Invalid configuration produces an actionable error" +ai-engineering discussion add WRK-0001 --kind NOTE --author human \ + --text "Record the current behavior before choosing a solution." + +ai-engineering status --format json +ai-engineering next-actions --format json ai-engineering work context WRK-0001 --format markdown ai-engineering project validate ``` -This creates `.ai-engineering/` beside your existing source files. A project with -`repositories: []` is fully supported; the workflow above does not require Git to be -installed. Its Works have no Git revision snapshots. Git becomes relevant when you -choose to register repositories. +`init` creates `.ai-engineering/` and installs portable instructions for agents, +including a managed block in the project's `AGENTS.md`. Existing project rules +outside that block are preserved. Keep the canonical engineering files under +version control when you use Git; `.ai-engineering/.local/` contains local state. -If the project folder is itself an existing Git repository, you can register it: +The exported context brings together the Work's scope, discussion, decisions, +plans, evidence references, and pending questions. `next-actions` suggests what to +address next. Every command provides `--help`; inspection commands support JSON. + +### Use existing Git repositories + +Git is required when registering or inspecting source repositories. In a project +that already contains `api/` and `web/` Git repositories, register them explicitly: ```sh -ai-engineering repo add app --path . -ai-engineering work create "Investigate a change" --repo app +ai-engineering repo add api --path api --language java +ai-engineering repo add web --path web --language typescript +ai-engineering work create "Improve request validation" --repo api --repo web ``` -Registration is optional and defaults to read-only. For example, a standalone -`zelda-1/` project can keep `.ai-engineering/` directly inside `zelda-1/`, without -registering the separate runtime or editor repositories. Each Work explicitly selects -any registered repositories it needs with `--repo`. +For a project whose root is itself a Git repository, use `repo add app --path .`. +Registration defaults to read-only access and does not change Git configuration. +Each Work selects its repositories with `--repo`; registration is optional for +projects that only need engineering records. -## Discover and continue with an agent +## How work is recorded -`init` installs `.ai-engineering/README.md`, `AGENTS.md` and `protocol.json`. These -describe the protocol without a provider-specific skill. It also creates or updates -a marked AIE block in the project's root `AGENTS.md`, preserving rules outside the -block. Changed instruction files are backed up under `.local/backups/onboarding/`. -For an existing project, install the entry contract explicitly: +| Record | Purpose | +|---|---| +| Work | Goal, constraints, acceptance criteria, and lifecycle | +| Discussion | Observations, questions, proposals, and conclusions | +| Survey | Questions with suggested choices, free text, and answer history | +| Decision | A reviewed choice with explicit approval and revision history | +| Plan | Steps, dependencies, observed results, and evidence references | +| Artifact | Retained evidence with integrity metadata | + +Completed required plans can consolidate a Work automatically. The framework +checks recorded state and evidence integrity; it does not prove that arbitrary +acceptance criteria have been satisfied. Human approvals are recorded explicitly, +and system completion retains its own provenance. + +See the [protocol reference](docs/protocol.md) for commands, formats, lifecycle +rules, and recovery behavior. + +## AI agent integration + +Agents can discover the protocol through `AGENTS.md` and `.ai-engineering/`. +They start with `status`, `next-actions`, and `work context` to reconstruct the +current state. The entry contract is independent of any model provider. + +Optional local adapters integrate installed, authenticated Codex and Claude CLIs: ```sh -aie onboard -aie status --format json -aie next-actions --format json -aie work context WRK-0001 +ai-engineering agent doctor --format json +ai-engineering agent configure --adapter codex-cli --profile general --model default +ai-engineering agent configure --activity analyze --adapter claude-cli --profile reviewer ``` -Use `ai-engineering` if the optional `aie` alias is unavailable. `onboard` is -idempotent; it leaves Work records unchanged. `aie guide` reads the bundled guide -even outside a project; `aie guide --format json` shows the discovery manifest. -An agent that finds `.ai-engineering` can read its README and manifest directly. -The root instructions point agents to that entry. Automatic discovery still depends -on the agent inspecting project instructions; a CLI cannot force an arbitrary model -to inspect hidden folders or obey a protocol. Exported context includes the guide. +Adapters produce proposals and summaries that AIE validates before applying. +Provider authentication remains with the provider's CLI. Offline fixture adapters +are available for deterministic tests. See the [local CLI adapter guide](docs/cli-adapters.md) +for setup, invocation controls, provenance, and supported behavior. -## Inspect compatibility before updating +## Compatibility and updates + +Inspect a project before considering a format update: ```sh -aie project compatibility --format json +ai-engineering project compatibility --format json +ai-engineering project validate --format json ``` -`status` includes a compatibility summary. The diagnostic separates the installed -CLI release, protocol contract revision and actual storage formats, including record -history. `CURRENT` and `LEGACY_COMPATIBLE` both mean readable; neither requires a -migration. `UNSUPPORTED` and `INVALID` return exit 4 and identify affected files. -Validation of references and evidence remains `aie project validate`. +`CURRENT` and `LEGACY_COMPATIBLE` both indicate readable formats. Supported older +records remain readable without automatic normalization or reopening completed +Works. `onboard` refreshes entry instructions with backups while preserving Work +files. The [compatibility guide](docs/compatibility.md) explains contract versions, +storage formats, diagnostics, and future explicit migrations. -Keep completed Works in their existing formats. Older supported files are interpreted -in memory; reads and diagnostics never normalize them on disk. `aie onboard` updates -only entry instructions and the manifest, with backups. It refuses to overwrite a -newer unsupported contract. There is no required data migration in this release. -See [compatibility and evolution](docs/compatibility.md) for the version policy and -the contract for future migrations; no source-code inspection is needed by consumers. +## Development and verification -## Discuss topics and answer surveys - -Ideas remain Discussion entries, organized by Work-local topics. Existing discussion -threads appear as implicit topics without rewriting their files. A small Work starts -with topic `main`. Every survey question has suggestions and accepts free text: +The test suite requires JDK 25 and Git. Run the project checks with: ```sh -aie topic create WRK-0001 "Rendering" -aie discussion add WRK-0001 --topic TOP-0001 --kind SUGGESTION \ - --text "Compare two rendering approaches" --author agent -aie survey create WRK-0001 --title "Choose an investigation" -aie survey question WRK-0001 SVY-0001 --topic TOP-0001 \ - --text "Which approach should we investigate?" \ - --option "Measure the current renderer" --option "Prototype layers" --recommend 1 -aie survey show WRK-0001 SVY-0001 -aie survey answer WRK-0001 SVY-0001 QST-0001 --choice 1 --author human -# A new answer supersedes the previous one while preserving it: -aie survey answer WRK-0001 SVY-0001 QST-0001 \ - --text "Compare both with a small fixture" --author human -aie survey history WRK-0001 SVY-0001 --format json +./gradlew check ``` -Add `--multiple` when a question permits several selections, and repeat `--choice`. -`--text-file` accepts UTF-8 answers. `survey ask WRK-0001 SVY-0001` guides a human -at a console; use `--input-file answers.txt` for explicit prepared input. Type option -numbers separated by commas, or write a free-text answer (`text:` forces free text). -Recommendations never count as answers. Revised answers signal review; they do not -silently change accepted DECs or plans. Pending questions appear in next-actions. +Tests generate JUnit results and JaCoCo coverage. Open +`build/reports/jacoco/jacocoTestReport/html/index.html` for the coverage report. -## Exercise the agent contract +- [Jenkins pipeline and setup](files/config/README.md): tests, coverage gates, + report publication, and local Pipeline fixtures. +- [GitHub Actions workflow](.github/workflows/build.yml): JVM verification and + native build jobs. +- [Native smoke script](scripts/native-smoke.sh): verification of a built executable + in disposable projects. -The `fixture-general` and `fixture-reviewer` adapters perform predictable -test transformations, with no model API or real semantic analysis. Use a disposable -project to exercise the complete refinement flow: +## Documentation -```sh -mkdir aie-fixture -cd aie-fixture -aie init --name "Refinement fixture" --general-adapter fixture-general \ - --archive-policy reversible -aie work create "Compare ideas" -printf 'Rendering: measure layers\nInput: compare controls\n' > ideas.md -aie agent run WRK-0001 --task-file ideas.md --request-id first-ideas -aie survey ask WRK-0001 SVY-0001 -printf 'Synthetic observation for the contract test\n' > evidence.txt -aie artifact add WRK-0001 --file evidence.txt --purpose "Explicit fixture evidence" -aie agent configure --activity analyze --adapter fixture-reviewer -aie agent run WRK-0001 --task "analyze: compare the fixture proposals" --request-id analysis -aie agent run WRK-0001 --task "summarize current context" -aie agent history WRK-0001 --format json -aie work context WRK-0001 -aie project validate -``` +| Guide | Contents | +|---|---| +| [Protocol reference](docs/protocol.md) | Commands, records, approval, persistence, and recovery | +| [Compatibility](docs/compatibility.md) | Supported formats and update procedures | +| [Discussion and refinement](docs/discussion-slice.md) | Topics, surveys, and proposal handling | +| [Plan consolidation](docs/plan-consolidation.md) | Steps, results, and automatic completion | +| [EPIC coordination](docs/epics.md) | Relationships and completion policies across Works | +| [Local CLI adapters](docs/cli-adapters.md) | Provider setup and invocation contract | +| [Architecture](docs/architecture.md) | Module boundaries and implementation design | +| [Roadmap](docs/roadmap.md) | Implemented capabilities and planned work | +| [Verification notes](docs/experiments.md) | Recorded experiments and validation results | -General handles activities without a configured specialization; specialized configuration -wins. `--activity` selects explicitly. Fixture classification recognizes `analyze:` and -`summarize`; otherwise refinement groups one idea per line, optionally `Topic: idea`. -Profiles/models are fixture identifiers, not connections to an external provider. -The analyze fixture reads stored answers/evidence, archives one proposal under the -explicit policy and prepares another as a **draft** DEC. It never creates human approval. +## Contributing -`discussion archive WRK DSC --reason TEXT --evidence ART` requires policy `reversible` -and integrity-checked evidence; the default is `review-only`. `discussion restore` -requires a reason and retains the source and disposition history. Run records retain -requester, executor, source fingerprint, proposals and applied references. Identical -completed request IDs reuse their result; changed input is rejected. Context marks -older runs stale when sources change; summaries refresh only on an explicit new run. -See [the refinement contract](docs/discussion-slice.md) for format and failure limits. +Bug reports should include the AIE version, operating system, reproduction steps, +and expected and actual behavior. For proposed changes, explain the problem and +include relevant tests and documentation. Run `./gradlew check` before submitting +a pull request. -## Connect local Codex and Claude CLIs +Changes to persisted formats should preserve supported readers and historical +fixtures. The [architecture](docs/architecture.md) and [compatibility guide](docs/compatibility.md) +explain the existing contracts and how to evolve them. -`codex-cli` and `claude-cli` return typed Discussion/synthesis proposals that AIE -validates before applying. Install/authenticate each provider's CLI separately; -neither is required for ordinary AIE use or automated tests. AIE itself still needs -no JVM or Node at runtime. Check the local interface without contacting a model: +## License -```sh -aie agent doctor --format json -aie agent configure --adapter codex-cli --profile general --model default --timeout 120 -aie agent configure --activity analyze --adapter claude-cli --profile reviewer -aie agent run WRK-0001 --activity summarize --task "Summarize the recorded goals and open questions" -aie agent history WRK-0001 --format json -``` - -Model `default` omits the provider model flag; explicit model names are passed as one -argument. Profile is an AIE role instruction, not a vendor configuration file. General -handles activities without a specialization; provider failure does not silently -switch executors. Without `--activity`, general first classifies the request; ambiguous -requests can yield a clarification survey. Previous RUN outputs travel with context -as derived interpretations. They do not become verified evidence by being summarized. - -Calls use stdin, fixed arguments, a private temporary directory, provider tool controls -and timeout/output limits. Source repository working directories are not supplied. -Credentials stay in provider stores/environment. RUN provenance records observed CLI -version, configured role/model, duration and output digest; it does not claim an -unreported actual model. Transport errors leave canonical Work data unchanged. -For a nonstandard executable location, set `AIE_CODEX_EXECUTABLE` or -`AIE_CLAUDE_EXECUTABLE` locally. No arbitrary extra-arguments option is supported. - -Guided setup can collect general and activity-specific executors before writing files: - -```sh -aie init . --interactive -# Or provide explicit prepared UTF-8 answers: -aie init . --name "My Project" --interactive --input-file setup-answers.txt -``` - -`init .` without --name starts guidance when a console is present. `init --name TEXT` -stays noninteractive. No terminal/file or incomplete answers produces a diagnostic; -setup never calls a model. See [the CLI adapter contract](docs/cli-adapters.md) for -scope, supported controls, environment handling and actual validation results. - -## Review, execute and close - -Refine a draft with `decision update` (including `--text-file` for narrative), then -record an actual human approval. The following fixture assumes the human has agreed: - -```sh -aie decision update WRK-0001 DEC-0001 \ - --context "Resume a small project change" --approach "One bounded slice" \ - --rationale "Keep the result verifiable" --by agent --reason "Discussion refined" -aie decision accept WRK-0001 DEC-0001 \ - --by owner --reason "Explicitly agreed scope" --human-approved -aie plan create WRK-0001 --title "Deliver the slice" --decision DEC-0001 -aie plan step add WRK-0001 PLN-0001 --title "Implement and test" -# Execute the actual change/tests externally, then attach their observed result: -aie artifact add WRK-0001 --file result.txt --purpose "Actual verification result" -aie plan step status WRK-0001 PLN-0001 TSK-0001 COMPLETED \ - --by agent --reason "Recorded the observed test outcome" --evidence ART-0001 -# The last required step consolidates Plan and Work automatically. -aie work check WRK-0001 -aie work reconcile WRK-0001 --requester agent --format json -aie work archive WRK-0001 --by owner --reason "Delivery recorded" -``` - -The framework consolidates completed Plans and their recorded results, without a -model call or a new Work-level acceptance checklist. Unanswered questions/surveys, -draft DECs and explicit blocking states remain pending. Empty sets never complete. -`plan exclude WRK PLN [--step TSK] --by NAME --reason TEXT` reviews cancelled scope -while retaining its history. See [the contract](docs/plan-consolidation.md). - -Inspection-only Works without Plans retain human-reviewed `work complete`, with -criterion evidence and `--integration PATH` or `--no-integration-needed "Reason"`. -Human approval remains an explicit attestation for significant commitments; system -completion is recorded separately and does not prove arbitrary prose semantically. - -Plans are proportional: small Works need not have a DEC or plan. Plans can contain -multiple steps, `--depends-on TSK-0001`, acceptance criteria and recorded results. -Step execution requires completed dependencies and accepted referenced decisions; -completed steps require evidence. `plan update`, `plan step update` and status changes -allow explicit replanning. `decision reject` retains rejected proposals; -`decision revise` creates a linked draft whose approval supersedes the prior decision. -Use `decision history` / `plan history` to inspect snapshots and SHA-256 links. - -Archived and terminal Works reject edits. Resume with -`aie work reopen WRK-0001 --by owner --reason "New observation"`; previous completion -records and all files remain. `status` hides archived Works unless `--all` is supplied. -No housekeeping command deletes records or requires a Lesson document. Legacy agenda -and Lesson import is deliberately deferred until this replacement is established. - -## Coordinate an EPIC - -An EPIC is a Work coordinating other Works in the same engineering project. Create -each Work with its own scope/criteria and link it explicitly. All children are -important by default; nested EPICs are allowed, with one parent per Work and no cycles. - -```sh -aie work create "Coordinate delivery" --acceptance "The reviewed child results satisfy the delivery" -aie work create "First slice" --acceptance "First bounded result verified" -aie work create "Second slice" --acceptance "Second bounded result verified" -aie epic configure WRK-0001 --mode results --by agent --reason "Coordinate these slices" -aie epic link WRK-0001 WRK-0002 --by agent --reason "First delivery" -aie epic link WRK-0001 WRK-0003 --by agent --reason "Second delivery" -# Only after actual human review of the policy and parent/child scopes: -aie epic authorize WRK-0001 --by owner --reason "These results are sufficient for the parent criteria" --human-approved -aie epic show WRK-0001 --format json -aie epic check WRK-0001 -``` - -Children with Plans complete through deterministic Plan consolidation; inspection-only -children can use human-reviewed `work complete`. Each -lifecycle command checks affected ancestors and returns their status/pending results -to the caller. Once important children and the parent's local checks pass, RESULTS -auto-completes using an owned ART receipt. Its origin is SYSTEM_EPIC and -humanApproved is false; the separate policy delegation remains explicit and traceable. -No LLM performs the state checks, and arbitrary prose criteria are not semantically -proved by the framework. `--requester` / `--request-id` correlate lifecycle reports. - -An important cancelled child remains pending. Review a reduced scope with -`epic importance EPIC CHILD --optional --by NAME --reason TEXT`, then authorize the -revised policy explicitly. Optional children may remain open. Scope/link changes -invalidate prior authority. An empty important set never auto-closes. Use mode -`decomposition` when the parent delivers the decomposition itself: ordinary reviewed -completion applies and does not wait for child execution. - -Reopening an important child reopens RESULTS ancestors and retains prior delivery -records. Optional changes do not invalidate them. Explicitly reopening an EPIC -suspends its automatic authority so new children/scope can be planned. Inspect -policy revisions with `epic history`; `epic reconcile [WRK]` recovers missed -propagation from files and does not duplicate receipts/completions on repeated calls. -See [the EPIC contract](docs/epics.md) for recovery and publication limits. - -## Refine a Work - -Update agreed scope without editing YAML manually: - -```sh -ai-engineering work update WRK-0001 \ - --goal "Define and validate the next small slice" \ - --description "Scope refined during discussion" \ - --motivation "Continue from recorded evidence" \ - --constraint "Preserve existing source behavior" \ - --constraint "Use isolated test data" \ - --acceptance "A fresh execution reconstructs the context" \ - --format json -``` - -Only supplied fields change. `--title` is also available; changing it preserves the -Work ID and folder. Status, creator, creation time, repository snapshots and all -discussion/decision/artifact references are retained. Identical updates do not rewrite -the file or change its modification timestamp. `work status` remains the lifecycle -command; updating scope does not approve a decision. - -**List options replace the whole corresponding list.** Repeat `--constraint` or -`--acceptance` for every value to retain. Omitted lists are preserved. Clear them -explicitly with `--clear-constraints` or `--clear-acceptance`; a clear option cannot be -combined with values for the same list. Empty description/motivation strings clear -those fields; title, goal and individual list values must be nonblank. - -For longer discussion entries, write a Markdown draft and import it: - -```sh -ai-engineering discussion add WRK-0001 \ - --kind SUGGESTION --author agent \ - --text-file ./proposal.md -``` - -Choose exactly one of `--text` and `--text-file`. File paths resolve from the invocation -directory, including when `--project` points elsewhere. Files must contain nonblank -UTF-8 text and be at most 1 MiB. The complete content, including line endings and -Markdown, becomes discussion text; source front matter is not interpreted. The -source is read once and left unchanged. Use `artifact add` separately for evidence. - -## Multiple repositories in one project - -From an external project directory with existing `runtime/` and `studio/` Git -repositories, run: - -```sh -ai-engineering init --name "Prometeu" -ai-engineering repo add runtime --path runtime --language rust -ai-engineering repo add studio --path studio --language java -ai-engineering repo list --format json -ai-engineering work create "Improve scene editor" \ - --repo runtime --repo studio \ - --goal "Evaluate portable scene rendering" \ - --constraint "No external service" \ - --acceptance "A fresh execution reconstructs the context" -ai-engineering discussion add WRK-0001 --kind QUESTION \ - --text "Should we use layered Canvas?" -ai-engineering discussion add WRK-0001 --kind RESPONSE --responds-to DSC-0001 \ - --text "Run a rendering experiment first" -ai-engineering artifact add WRK-0001 --file result.txt \ - --purpose "Rendering measurements" --origin "manual experiment" -ai-engineering decision draft WRK-0001 --title "Evaluate layered Canvas" \ - --context "Scene editor rendering" --approach "Prototype layers" \ - --rationale "Measure before committing" --evidence ART-0001 -ai-engineering work context WRK-0001 --format markdown -ai-engineering work context WRK-0001 --format json -ai-engineering project validate -``` - -The CLI never initializes or modifies Git repositories. To register an existing -submodule use `--type git-submodule`; the default is `linked-git`. Repositories are -read-only unless registration explicitly includes `--allow-edit`. This is policy -metadata; it does not replace an operating-system sandbox. No source edits or -configured validation commands are executed in these milestones. - -`--project /path/to/project` works before or after subcommands. Otherwise discovery -searches upward, including when invoked inside a nested source directory. -Work IDs use uppercase hexadecimal with at least four digits: -`WRK-0009`, `WRK-000A`, …, `WRK-000F`, `WRK-0010`. Existing IDs retain their spelling; -legacy counters are upgraded when the next Work is created, without reusing reserved -IDs. Child IDs remain decimal and are scoped to their Work. New discussions can -be grouped with `--discussion `. History remains append-only. `work status -WRK-0001 ACTIVE` changes an open Work's lifecycle status. Completion uses -Plan consolidation or human-reviewed `work complete` for inspection-only Works; -terminal Works return to ACTIVE through `work reopen`. -Every command provides `--help`; inspection commands support `--format json`. - -New discussion files keep metadata in YAML front matter (`documentVersion: 2`) and -the complete text in the Markdown body. Headings, lists, tables and code blocks remain -readable directly in an editor. Markdown context/list output also displays prose -directly; JSON continues to expose the same `text` field. - -Older discussion files with `text` in YAML are read without being rewritten. To -convert a Work's existing discussions explicitly with the updated CLI: - -```sh -ai-engineering discussion migrate WRK-0001 -``` - -Originals are backed up under `.ai-engineering/.local/backups/discussions/`; the -command reports the backup paths. IDs, authors, dates, text, Work metadata and exported -context data are preserved. Running the command again skips converted files. Migration -refuses legacy trailing notes rather than silently dropping them. Use the updated CLI -for files in document version 2; old CLI builds cannot read that new file format. - -Exit codes: **0** success, **1** unexpected I/O/runtime failure, **2** invalid input -or unsafe path, **3** missing project/resource, **4** structural validation failure. -Validation commands return 4 with diagnostics even when the underlying issue is a -missing referenced resource or unsafe persisted path. - -## Architecture and protocol - -One Gradle project, one Spring Boot application, ten verified Modulith modules: -project, work, discussion, decision, planning, artifact, agent, verification, CLI and shared filesystem -infrastructure. Domain state is immutable Java records; persistence uses versioned -YAML and Markdown front matter. Files remain understandable without this CLI. - -- [Architecture and reuse decisions](docs/architecture.md) -- [Protocol schema and persistence guarantees](docs/protocol.md) -- [Roadmap and acceptance criteria](docs/roadmap.md) -- [Experiments and actual validation results](docs/experiments.md) - -No Agenda, Lesson or autonomous OODA engine is part of this implementation. Local -Codex/Claude integrations are limited to proposals; EPIC/conformance/state checks -run in framework code. The two fixture adapters remain available for offline use. +Licensed under the [MIT License](LICENSE). diff --git a/build.gradle.kts b/build.gradle.kts index 41c0cfc..da8f3a0 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -10,6 +10,10 @@ plugins { group = "net.intrepid" version = "0.1.0" +tasks.withType().configureEach { + from("LICENSE") { into("META-INF") } +} + java { toolchain { languageVersion = JavaLanguageVersion.of(25) } } repositories { mavenCentral() } dependencies { @@ -78,7 +82,7 @@ tasks.register("nativeDistZip") { include("ai-engineering", "ai-engineering.exe") filePermissions { unix("rwxr-xr-x") } } - from("README.md") + from("README.md", "LICENSE") from("docs") { into("docs") } } tasks.register("nativeDistTar") { @@ -89,6 +93,6 @@ tasks.register("nativeDistTar") { compression = Compression.GZIP destinationDirectory = layout.buildDirectory.dir("distributions") from(layout.buildDirectory.dir("native/nativeCompile")) { include("ai-engineering"); filePermissions { unix("rwxr-xr-x") } } - from("README.md") + from("README.md", "LICENSE") from("docs") { into("docs") } }