bquarkz 20bb4f02bc
build / jvm (push) Waiting to run
build / native (macos-15, macos-arm64) (push) Waiting to run
build / native (ubuntu-24.04, linux-x86_64) (push) Waiting to run
build / native (windows-2025, windows-x86_64) (push) Waiting to run
Test / Tests and coverage
Intrepid/AI Engineering/pipeline/head This commit looks good
chore: keep AI Engineering workspace local
2026-11-22 15:38:18 +00:00

AI Engineering

MIT License · Quick start · Documentation · 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.

./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:

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, Native Image, a C/C++ toolchain and Python 3:

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. 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:

./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:

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:

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:

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:

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 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 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.

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:

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 for setup, invocation controls, provenance, and supported behavior.

Compatibility and updates

Inspect a project before considering a format update:

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.

Development and verification

The test suite requires JDK 25 and Git. Run the project checks with:

./gradlew check

Tests generate JUnit results and JaCoCo coverage. Open build/reports/jacoco/jacocoTestReport/html/index.html for the coverage report.

Documentation

Guide Contents
Protocol reference Commands, records, approval, persistence, and recovery
Compatibility Supported formats and update procedures
Storage migration Preview, apply, recover and rollback
Work conduct and OODA Human discussion choices, DEC authority and optional Plan experiments
Discussion and refinement Topics, surveys, and proposal handling
Plan consolidation Steps, results, and automatic completion
EPIC coordination Relationships and completion policies across Works
Local CLI adapters Provider setup and invocation contract
Architecture Module boundaries and implementation design
Roadmap Implemented capabilities and planned work
Verification notes 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 and compatibility guide explain the existing contracts and how to evolve them.

License

Licensed under the MIT License.

S
Description
No description provided
Readme MIT
1.6 MiB
Languages
Java 91.3%
Shell 5.5%
Python 2.5%
Groovy 0.7%