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

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:

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.

Start in a simple project

Run inside the folder you already use for your application, game or library:

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:

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:

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:

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.

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

S
Description
No description provided
Readme MIT
3.3 MiB
Languages
Java 91.2%
Shell 6.5%
Python 1.4%
Groovy 0.9%