Files
ai-engineering/README.md
T
bquarkz b91829270b feat: bootstrap portable engineering protocol CLI
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.
2026-11-11 16:14:22 +00:00

6.1 KiB

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.

No Agenda, Lesson, autonomous OODA engine, agent orchestration or concrete AI adapter is part of this implementation.