Files
ai-engineering/README.md
T
Nilton Constantino c84bb8d36f feat: store discussion prose in Markdown bodies
Add versioned Markdown discussion documents with legacy YAML reading and explicit migration that backs up originals and preserves semantic history.

Render readable discussion and decision prose in Markdown context, document compatibility, and extend native smoke coverage for migration.

Validated with 29 passing tests, macOS ARM64 native smoke, and context-preserving migration of the Zelda pilot Work.
2026-11-11 19:50:36 +00:00

179 lines
8.3 KiB
Markdown

# 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,
draft decisions and evidence so another person or agent can continue without chat history.
Milestones 0 and 1 are implemented. The application runs locally in non-web mode;
it needs no model API, database or running service.
## Build and run
Build requirements: JDK 25, Git (for repository inspection and integration fixtures),
and internet access for the first dependency download. The Gradle Wrapper is included.
The recommended local toolchain is GraalVM Community Edition, pinned in `.sdkmanrc`.
With SDKMAN installed, activate it from the project root:
```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).
```sh
./gradlew nativeCompile
./build/native/nativeCompile/ai-engineering --help
./gradlew nativeDistZip nativeDistTar -PtargetPlatform=macos-arm64
bash scripts/native-smoke.sh "$PWD/build/native/nativeCompile/ai-engineering"
```
Archives are written to `build/distributions/ai-engineering-0.1.0-<platform>.*`.
Build each binary on its target OS/architecture; Native Image is not a general cross
compiler. CI defines Linux x86_64, macOS ARM64 and Windows x86_64 native builds.
macOS x86_64 remains a target with an upstream toolchain availability limitation:
GraalVM 25 dropped that port; see [roadmap](docs/roadmap.md). Local verification
results, including which native binaries were actually tested, are in [experiments](docs/experiments.md).
## Start in a simple project
Run inside the folder you already use for your application, game or library:
```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"
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.
If the project folder is itself an existing Git repository, you can register it:
```sh
ai-engineering repo add app --path .
ai-engineering work create "Investigate a change" --repo app
```
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`.
## 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 are stable (`WRK-0001`); child IDs are scoped to their Work. New discussions can
be grouped with `--discussion <name>`. History remains append-only. `work status
WRK-0001 ACTIVE` changes lifecycle status; all initial statuses are reversible.
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, eight verified Modulith modules:
project, work, discussion, decision, artifact, 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, autonomous OODA engine, agent orchestration or concrete AI adapter
is part of this implementation.