313 lines
14 KiB
Markdown
313 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 quality results in a local SQLite database for each project.
|
|
|
|
Use it in a single folder or across several source repositories. Git is optional.
|
|
SQLite runs inside AIE; no database server, model API or background service is required.
|
|
State stays outside Git by default. Versioning it is the developer's choice.
|
|
|
|
## 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.
|
|
|
|
### Prepare a native package
|
|
|
|
On Linux (x64/ARM64) and macOS (Apple Silicon), use the GraalVM JDK 25 pinned in
|
|
[.sdkmanrc](.sdkmanrc), Native Image, a C/C++ toolchain and Python 3:
|
|
|
|
```sh
|
|
sdk env install
|
|
sdk env
|
|
export GRAALVM_HOME="$JAVA_HOME"
|
|
./gradlew nativePackage
|
|
python3 scripts/verify-native-package.py build/native/package
|
|
./gradlew nativeDistZip nativeDistTar
|
|
```
|
|
|
|
These commands prepare build outputs. The complete package contains AIE, the
|
|
companion JDBC/native libraries and a pinned `sqlite3` diagnostic executable.
|
|
Keep those components together; copying the AIE executable alone is insufficient.
|
|
SQLite source is checksum-pinned in [sqlite-version.json](scripts/sqlite-version.json).
|
|
Distributions are written to `build/distributions/` with docs and licenses.
|
|
Build on the intended OS/architecture. macOS Intel uses the JVM distribution.
|
|
|
|
### Install when ready
|
|
|
|
Installation is a separate action. From a checkout:
|
|
|
|
```sh
|
|
./scripts/install-native.sh
|
|
```
|
|
|
|
The script prepares and verifies the complete package before activation. It uses a
|
|
compatible `GRAALVM_HOME`/`JAVA_HOME`, or obtains the pinned GraalVM through SDKMAN.
|
|
Defaults are `~/.local/lib/ai-engineering` for releases and `~/.local/bin` for
|
|
`ai-engineering`, `aie` and `aie-sqlite3` shortcuts. Project databases stay in their
|
|
projects. Failed checks preserve the prior installation; activation failures restore
|
|
the prior release/shortcuts. No project is migrated by installation.
|
|
|
|
Use `--lib-dir DIR --bin-dir DIR` for custom destinations. The script does not edit
|
|
shell profiles or install system packages. Add your bin directory to PATH yourself.
|
|
Native builds require platform C/C++ and zlib development tools; SDKMAN bootstrap
|
|
also needs curl, zip and unzip. Installer verification uses Python 3.
|
|
|
|
## 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 work guidance WRK-0001 --mode DIRECT --by human \
|
|
--reason "Human chose a direct discussion" --human-approved
|
|
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. New state is SQLite and `/.ai-engineering/` is
|
|
added to .gitignore, even without Git installed. `init --version-state` leaves ignore
|
|
policy to you. Existing tracked files are never untracked automatically.
|
|
|
|
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.
|
|
|
|
In guided Works, creating a Plan from a draft decision requires an explicit
|
|
Work-wide human waiver; otherwise approve the DEC first. Eligible promotion changes it 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 | Temporary check input with integrity and retirement state |
|
|
| Quality gate | Required project/Work check and state-bound observed result |
|
|
|
|
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.
|
|
|
|
## Quality and retention
|
|
|
|
Investigation/discussion and implementation remain connected through DEC and Plan.
|
|
OODA guides experiments and reconsideration. Required gates come from the project,
|
|
with additional gates per Work; pending, failed or stale checks block delivery.
|
|
Checks run externally. AIE records the actual observation against an evaluated
|
|
state and keeps a short result; human approval is separate.
|
|
|
|
Evidence attachments stay available while checks need them. After Work completion,
|
|
new temporary copies retire automatically; missing input before a check is an error.
|
|
Outputs requested by the user belong at their delivery destination outside AIE state.
|
|
Internal receipts are structured database facts. Legacy originals and migration safety
|
|
copies remain preserved. See [gates and retention](docs/protocol.md#quality-gates).
|
|
|
|
## 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 without converting storage. To move a
|
|
legacy project to SQLite, review `aie storage migrate --format json`, then apply
|
|
with its fingerprint. See [migration and recovery](docs/storage-migration.md).
|
|
|
|
## 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 |
|
|
| [Storage migration](docs/storage-migration.md) | Preview, apply, recover and rollback |
|
|
| [Work conduct and OODA](docs/work-guidance.md) | Human discussion choices, DEC authority and optional Plan experiments |
|
|
| [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).
|