Files
bquarkz f5d5db73c2
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/AI Engineering/pipeline/head There was a failure building this commit
build / jvm (push) Canceled after 0s
build / native (macos-15, macos-arm64) (push) Canceled after 0s
build / native (ubuntu-24.04, linux-x86_64) (push) Canceled after 0s
build / native (windows-2025, windows-x86_64) (push) Canceled after 0s
feat: add Work guidance and adaptive Plan experiments
Persist explicit human discussion choices, DEC requests and approval policies. Add optional evidence-backed Plan experiments and align context, adapters and next actions under protocol contract 3.

Include WRK-000B decisions, plan history and verification evidence: 167 JVM tests, 25 focused checks, Jenkins fixtures and native smoke coverage.
2026-11-16 17:33:24 +00:00

320 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 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. 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.
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 | 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 |
| [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).