Allow registering a single Git repository at the engineering project root with --path . while retaining path safety checks. Document Git-optional projects first and cover plain folders, root repositories, and multiple repositories in process tests and native smoke scenarios. Validated with 23 passing tests and macOS ARM64 native smoke checks for all three layouts.
161 lines
7.4 KiB
Markdown
161 lines
7.4 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`.
|
|
|
|
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.
|