316 lines
14 KiB
Markdown
316 lines
14 KiB
Markdown
# AI Engineering
|
|
|
|
[MIT License](LICENSE) · [Quick start](#quick-start) · [Documentation](#documentation) · [Contributing](#contributing)
|
|
|
|
AI Engineering (AIE) is a local CLI for keeping engineering work understandable
|
|
across people, AI agents, and sessions. It stores goals, discussions, decisions,
|
|
plans, and verification evidence as readable files alongside your project.
|
|
|
|
Use it in a single folder or across several source repositories. Git is optional.
|
|
The core workflow runs without a model API, database, or background service.
|
|
|
|
## What you can do
|
|
|
|
- **Preserve context:** resume a Work from recorded goals, discussion, decisions,
|
|
and evidence instead of relying on chat history.
|
|
- **Refine ideas:** organize topics, collect answers through surveys, and retain
|
|
the history when an answer or decision changes.
|
|
- **Track delivery:** connect plans, dependencies, observed results, and evidence;
|
|
consolidate completed plans through deterministic checks.
|
|
- **Coordinate repositories:** explicitly select the repositories involved in each
|
|
Work, while keeping engineering records in one project.
|
|
- **Work with AI agents:** provide portable entry instructions and structured
|
|
context; optionally use local Codex or Claude CLIs for proposals and summaries.
|
|
- **Retain history:** read supported older formats without rewriting completed
|
|
Works, approvals, or evidence.
|
|
|
|
A **Work** is the unit of engineering activity: a scoped problem or change with
|
|
its own context and history. Decisions and plans are added when the work needs them.
|
|
AIE records the work and checks its structure; people and agents choose solutions,
|
|
change source code, run tests, and assess the results.
|
|
|
|
## Installation
|
|
|
|
### Run from source
|
|
|
|
Clone this repository and open its root directory. Building the JVM application
|
|
requires **JDK 25** and access to dependency repositories on the first build.
|
|
The Gradle Wrapper is included; a separate Gradle installation is unnecessary.
|
|
|
|
```sh
|
|
./gradlew bootJar
|
|
java -jar build/libs/ai-engineering-0.1.0.jar --help
|
|
```
|
|
|
|
For the examples below, you can define a command in your current POSIX shell.
|
|
Run this from the repository root so the JAR path stays valid after changing folders:
|
|
|
|
```sh
|
|
export AIE_JAR="$PWD/build/libs/ai-engineering-0.1.0.jar"
|
|
ai-engineering() { java -jar "$AIE_JAR" "$@"; }
|
|
```
|
|
|
|
The JAR requires Java 25 at runtime. On Windows, use `gradlew.bat` in place of
|
|
`./gradlew`; you can invoke the JAR directly with `java -jar` and its full path.
|
|
|
|
### Build a native executable
|
|
|
|
On Linux (x64/ARM64) and macOS (Apple Silicon), build and install for your user:
|
|
|
|
```sh
|
|
./scripts/install-native.sh
|
|
```
|
|
|
|
The script uses a compatible `GRAALVM_HOME` or `JAVA_HOME`, otherwise installs the
|
|
GraalVM version pinned in `.sdkmanrc` through [SDKMAN](https://sdkman.io/install/),
|
|
installing SDKMAN too when needed. It builds with the Gradle Wrapper, checks the
|
|
executable, copies it to `~/.local/bin/ai-engineering`, and creates the `aie`
|
|
shortcut. Run the same command again to update. The installed copy works independently
|
|
of this checkout. A failed build or executable check leaves the previous installation
|
|
in place. Downloads require internet access.
|
|
|
|
If `~/.local/bin` is not in your `PATH`, add this to your shell profile and current
|
|
session (the script prints the appropriate command for your destination):
|
|
|
|
```sh
|
|
export PATH="$HOME/.local/bin:$PATH"
|
|
aie --help
|
|
```
|
|
|
|
Use `./scripts/install-native.sh --bin-dir /path/to/bin` to select another destination.
|
|
The script can be invoked from any directory and does not modify shell profiles or
|
|
install system packages. It requires `curl`, `zip`, and `unzip` when installing GraalVM
|
|
through SDKMAN. Install [native build prerequisites](https://www.graalvm.org/jdk25/reference-manual/native-image/)
|
|
before running it:
|
|
|
|
- macOS: `xcode-select --install` (Apple Command Line Tools).
|
|
- Debian/Ubuntu: `sudo apt-get install build-essential zlib1g-dev`.
|
|
- Fedora/RHEL: `sudo dnf install gcc gcc-c++ glibc-devel zlib-devel libstdc++-static`.
|
|
|
|
The pinned GraalVM does not support macOS Intel; use the JVM instructions above.
|
|
|
|
For a manual native build:
|
|
|
|
The native executable runs without a JVM. Building it requires **GraalVM for
|
|
JDK 25**, Native Image, and a C/C++ toolchain for the target platform. Set both
|
|
`JAVA_HOME` and `GRAALVM_HOME` to your GraalVM installation.
|
|
|
|
If you use SDKMAN, the repository pins a compatible toolchain in [.sdkmanrc](.sdkmanrc):
|
|
|
|
```sh
|
|
sdk env install
|
|
sdk env
|
|
export GRAALVM_HOME="$JAVA_HOME"
|
|
./gradlew nativeCompile
|
|
./build/native/nativeCompile/ai-engineering --help
|
|
```
|
|
|
|
Add the executable's directory to `PATH` to use `ai-engineering` from other folders.
|
|
On Windows the executable is named `ai-engineering.exe`. The shorter `aie` command
|
|
can be provided as a local alias or symlink.
|
|
|
|
To create distribution archives:
|
|
|
|
```sh
|
|
./gradlew nativeDistZip nativeDistTar
|
|
```
|
|
|
|
Archives are written to `build/distributions/` and include the README, documentation,
|
|
and MIT license. Build on the intended OS and architecture; the native CI matrix
|
|
is defined in [.github/workflows/build.yml](.github/workflows/build.yml).
|
|
|
|
## Quick start
|
|
|
|
With the CLI available, create an engineering workspace in a new folder:
|
|
|
|
```sh
|
|
mkdir my-project
|
|
cd my-project
|
|
|
|
ai-engineering init --name "My Project"
|
|
ai-engineering work create "Improve configuration errors" \
|
|
--goal "Make invalid configuration easier to diagnose" \
|
|
--acceptance "Invalid configuration produces an actionable error"
|
|
ai-engineering discussion add WRK-0001 --kind NOTE --author human \
|
|
--text "Record the current behavior before choosing a solution."
|
|
|
|
ai-engineering status --format json
|
|
ai-engineering next-actions --format json
|
|
ai-engineering work context WRK-0001 --format markdown
|
|
ai-engineering project validate
|
|
```
|
|
|
|
`init` creates `.ai-engineering/` and installs portable instructions for agents,
|
|
including a managed block in the project's `AGENTS.md`. Existing project rules
|
|
outside that block are preserved. Keep the canonical engineering files under
|
|
version control when you use Git; `.ai-engineering/.local/` contains local state.
|
|
|
|
The exported context brings together the Work's scope, discussion, decisions,
|
|
plans, evidence references, and pending questions. `next-actions` suggests what to
|
|
address next. Every command provides `--help`; inspection commands support JSON.
|
|
|
|
### Choose the next Work
|
|
|
|
`work list`, `status`, and `next-actions` accept `--format table|csv|markdown|json`.
|
|
Markdown is the default and renders actual tables. Use aligned tables in the
|
|
terminal, CSV for spreadsheets, and JSON for the existing full structured records:
|
|
|
|
```sh
|
|
aie work list --open --format table
|
|
aie status --format table
|
|
aie next-actions --format table
|
|
aie work list --open --format csv > open-works.csv
|
|
aie next-actions WRK-0001 --format csv > next-actions.csv
|
|
```
|
|
|
|
Work summaries show ID, title, status, archive flag, completed/total steps,
|
|
pending action count, validation, and the next suggested command. Steps count
|
|
all registered Plans, including cancelled steps in the total; `0/0` means no
|
|
steps are registered, and `unavailable` means Plan data could not be read.
|
|
Pending actions are the deterministic suggestions from `next-actions`, including
|
|
execution, questions, decision review, dependencies, repairs, and archival.
|
|
They are not a count of blockers or a priority ranking. Use `next-actions WRK`
|
|
to inspect every suggestion and its explanation.
|
|
|
|
`--open` includes OPEN, ACTIVE, and BLOCKED Works and excludes completed,
|
|
cancelled, and archived Works, in every format. Without this filter, `work list`
|
|
continues to include all Works. `status` hides archived Works unless `--all` is
|
|
given. JSON schemas and default formats elsewhere are unchanged. CSV uses UTF-8,
|
|
comma separators, a fixed header, CRLF record endings, and quoted fields when
|
|
needed; original multiline text is preserved. CSV contains just the table,
|
|
including a header for empty results. Markdown escapes cell content and table
|
|
output flattens line breaks and control characters. These commands only read
|
|
project records and never invoke a model.
|
|
|
|
### Use existing Git repositories
|
|
|
|
Git is required when registering or inspecting source repositories. In a project
|
|
that already contains `api/` and `web/` Git repositories, register them explicitly:
|
|
|
|
```sh
|
|
ai-engineering repo add api --path api --language java
|
|
ai-engineering repo add web --path web --language typescript
|
|
ai-engineering work create "Improve request validation" --repo api --repo web
|
|
```
|
|
|
|
For a project whose root is itself a Git repository, use `repo add app --path .`.
|
|
Registration defaults to read-only access and does not change Git configuration.
|
|
Each Work selects its repositories with `--repo`; registration is optional for
|
|
projects that only need engineering records.
|
|
|
|
## How work is recorded
|
|
|
|
Open Discussion Framework agendas can be imported with a read-only preview:
|
|
|
|
```sh
|
|
aie import discussion --source app=../app --format json
|
|
aie import discussion --source app=../app --apply --expect <preview-fingerprint>
|
|
```
|
|
|
|
One Work receives each DSC's open agendas in full. Repeat `--source` for an
|
|
umbrella, and use `--target SOURCE=TEXT` to describe its targets. Identical imports
|
|
are skipped; changes require review without overwriting. See
|
|
[Discussion Framework import](docs/discussion-import.md) for the contract and limits.
|
|
|
|
Creating a Plan from a draft decision automatically promotes that decision to
|
|
ACCEPTED. The framework records the causal Plan and system provenance without a
|
|
model call. Direct human approval remains available through `decision accept`.
|
|
|
|
| Record | Purpose |
|
|
|---|---|
|
|
| Work | Goal, constraints, acceptance criteria, and lifecycle |
|
|
| Discussion | Observations, questions, proposals, and conclusions |
|
|
| Survey | Questions with suggested choices, free text, and answer history |
|
|
| Decision | A reviewed choice with explicit approval and revision history |
|
|
| Plan | Steps, dependencies, observed results, and evidence references |
|
|
| Artifact | Retained evidence with integrity metadata |
|
|
|
|
Completed required plans can consolidate a Work automatically. The framework
|
|
checks recorded state and evidence integrity; it does not prove that arbitrary
|
|
acceptance criteria have been satisfied. Human approvals are recorded explicitly,
|
|
and system completion retains its own provenance.
|
|
|
|
See the [protocol reference](docs/protocol.md) for commands, formats, lifecycle
|
|
rules, and recovery behavior.
|
|
|
|
## AI agent integration
|
|
|
|
Agents can discover the protocol through `AGENTS.md` and `.ai-engineering/`.
|
|
They start with `status`, `next-actions`, and `work context` to reconstruct the
|
|
current state. The entry contract is independent of any model provider.
|
|
|
|
Optional local adapters integrate installed, authenticated Codex and Claude CLIs:
|
|
|
|
```sh
|
|
ai-engineering agent doctor --format json
|
|
ai-engineering agent configure --adapter codex-cli --profile general --model default
|
|
ai-engineering agent configure --activity analyze --adapter claude-cli --profile reviewer
|
|
```
|
|
|
|
Adapters produce proposals and summaries that AIE validates before applying.
|
|
Provider authentication remains with the provider's CLI. Offline fixture adapters
|
|
are available for deterministic tests. See the [local CLI adapter guide](docs/cli-adapters.md)
|
|
for setup, invocation controls, provenance, and supported behavior.
|
|
|
|
## Compatibility and updates
|
|
|
|
Inspect a project before considering a format update:
|
|
|
|
```sh
|
|
ai-engineering project compatibility --format json
|
|
ai-engineering project validate --format json
|
|
```
|
|
|
|
`CURRENT` and `LEGACY_COMPATIBLE` both indicate readable formats. Supported older
|
|
records remain readable without automatic normalization or reopening completed
|
|
Works. `onboard` refreshes entry instructions with backups while preserving Work
|
|
files. The [compatibility guide](docs/compatibility.md) explains contract versions,
|
|
storage formats, diagnostics, and future explicit migrations.
|
|
|
|
## Development and verification
|
|
|
|
The test suite requires JDK 25 and Git. Run the project checks with:
|
|
|
|
```sh
|
|
./gradlew check
|
|
```
|
|
|
|
Tests generate JUnit results and JaCoCo coverage. Open
|
|
`build/reports/jacoco/jacocoTestReport/html/index.html` for the coverage report.
|
|
|
|
- [Jenkins pipeline and setup](files/config/README.md): tests, coverage gates,
|
|
report publication, and local Pipeline fixtures.
|
|
- [GitHub Actions workflow](.github/workflows/build.yml): JVM verification and
|
|
native build jobs.
|
|
- [Native smoke script](scripts/native-smoke.sh): verification of a built executable
|
|
in disposable projects.
|
|
|
|
## Documentation
|
|
|
|
| Guide | Contents |
|
|
|---|---|
|
|
| [Protocol reference](docs/protocol.md) | Commands, records, approval, persistence, and recovery |
|
|
| [Compatibility](docs/compatibility.md) | Supported formats and update procedures |
|
|
| [Discussion and refinement](docs/discussion-slice.md) | Topics, surveys, and proposal handling |
|
|
| [Plan consolidation](docs/plan-consolidation.md) | Steps, results, and automatic completion |
|
|
| [EPIC coordination](docs/epics.md) | Relationships and completion policies across Works |
|
|
| [Local CLI adapters](docs/cli-adapters.md) | Provider setup and invocation contract |
|
|
| [Architecture](docs/architecture.md) | Module boundaries and implementation design |
|
|
| [Roadmap](docs/roadmap.md) | Implemented capabilities and planned work |
|
|
| [Verification notes](docs/experiments.md) | Recorded experiments and validation results |
|
|
|
|
## Contributing
|
|
|
|
Bug reports should include the AIE version, operating system, reproduction steps,
|
|
and expected and actual behavior. For proposed changes, explain the problem and
|
|
include relevant tests and documentation. Run `./gradlew check` before submitting
|
|
a pull request.
|
|
|
|
Changes to persisted formats should preserve supported readers and historical
|
|
fixtures. The [architecture](docs/architecture.md) and [compatibility guide](docs/compatibility.md)
|
|
explain the existing contracts and how to evolve them.
|
|
|
|
## License
|
|
|
|
Licensed under the [MIT License](LICENSE).
|