Implement milestones 0 and 1 with project and repository configuration, Work persistence, discussions, draft decisions, evidence integrity, and deterministic context exports. Add Java 25, Spring Boot and Modulith, native distributions, CI workflows, protocol documentation, and the pinned SDKMAN GraalVM CE toolchain. Validated with 20 passing tests and the macOS ARM64 native multi-repository continuity smoke.
ai-engineering
An open, agent-agnostic engineering protocol and CLI. Works belong to an engineering project spanning independent repositories. 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:
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.
./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.
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).
./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. Local verification
results, including which native binaries were actually tested, are in experiments.
Two-repository example
From an external project directory with existing runtime/ and studio/ Git
repositories, run:
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.
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
- Protocol schema and persistence guarantees
- Roadmap and acceptance criteria
- Experiments and actual validation results
No Agenda, Lesson, autonomous OODA engine, agent orchestration or concrete AI adapter is part of this implementation.