Files
ai-engineering/src/main/resources/protocol/README.md
T
Nilton Constantino bd2c9133da feat: add agent coordination and automatic work completion
Add portable topics and surveys, decision approval history, execution plans, local Codex and Claude adapters, and general agent routing. Consolidate Plan and EPIC results through deterministic completion receipts, reviewed cancellation scope and recoverable reconciliation.

Track the completed WRK-0001 and WRK-0002 records, protocol documentation, source manifests and delivery evidence.

Validation: 117 tests including Modulith; GraalVM 25 native compilation, standalone smoke and ZIP/TAR verification on macOS ARM64; identical persisted context across JVM and native executions.
2026-11-14 01:12:21 +00:00

14 KiB

AI Engineering — agent entry point

This project uses the portable AI Engineering protocol. The presence of .ai-engineering/ identifies the engineering workspace. Read this document and protocol.json, then the project's root AGENTS.md and applicable local rules. The closest enclosing .ai-engineering owns the current project; repository count and Git availability are optional. Preserve project instructions outside AIE's block.

Starting or continuing work

Use ai-engineering (or its installed alias aie). No server or model API is needed.

  1. Run aie status --format json and aie next-actions --format json.
  2. Locate the requested Work, or create one with aie work create "Title" after understanding the request. If the intended Work/scope is ambiguous, clarify it.
  3. Run aie work context WRK-0001 --format markdown. Read referenced evidence payloads, decisions and plan history when relevant; context references are not the payload itself. Without a CLI, inspect the versioned files directly.
  4. Distinguish observations verified now, historical evidence, assumptions and proposals. Record refinement with discussion add --text or --text-file, choosing an explicit --author. Resolve questions with RESPONSE/CONCLUSION entries linked by --responds-to; a suggestion is not approval.
  5. Refine agreed goal/constraints/criteria using work update. List options replace whole lists. Use DEC drafts for significant commitments; small work need not invent a decision or plan merely to satisfy a ceremony.

Topics, surveys and refinement

Discussion remains the refinement space: receive ideas, organize topics, investigate, record results and prepare decisions. Use topic create/list/show/update to organize formal topics; legacy discussion threads appear as implicit topics without rewriting their files. Use discussion add --topic TOP-0001 for entries on a formal topic.

survey create WRK --title TEXT creates a survey. Add questions with survey question WRK SVY --text TEXT --option TEXT --option TEXT [--topic TOP]. Options are numbered from 1. --recommend 1 suggests an option; --multiple allows more than one selected choice. Every question has suggestions and accepts free text. survey answer WRK SVY QST --choice 1 [--text TEXT] records an answer; --text-file accepts a UTF-8 answer file. A later answer supersedes the prior one, preserving history and signaling that related conclusions may need review.

survey show/list/history and Work context expose questions, latest and prior answers. survey ask WRK SVY guides a human at a console; --input-file supports an explicit prepared input. Enter option numbers separated by commas or free text; prefix numeric free text with text:. Noninteractive agents should use answer. Unanswered questions and empty surveys remain visible completion-readiness issues.

discussion archive WRK DSC --reason TEXT --evidence ART records a reversible disposition when archivePolicy is explicitly reversible; its default is review-only. discussion restore requires a reason and keeps original history. Archive preserves proposals and requires owned integrity-checked evidence.

Deterministic adapter experiment

The fixture-general and fixture-reviewer adapters exercise the contract and produce labeled fixture results, not real model research or semantic intelligence. agent list lists them. Configure general with agent configure --adapter fixture-general [--archive-policy reversible] or initialize with init --name TEXT --general-adapter fixture-general. Configure a specialized activity with agent configure --activity analyze --adapter fixture-reviewer. Profile/model are identifiers for this fixture contract.

agent run WRK --task TEXT [--activity NAME] [--request-id KEY] selects the configured activity executor, or general when no specialization exists. In refine fixtures, use one idea per line and optional Topic: idea labels. Task prefixes analyze: and summarize select fixture activities when no activity is given. Fake analyze reads persisted answers and explicit fixture evidence; it may propose reversible archive under policy and a DEC draft, never a human approval.

agent show/history exposes requester, selected executor, source fingerprint, proposals, applied references and failures. Reusing a completed request ID with identical input reuses that result; different input is rejected. Pending/failed application is inspectable. Context marks runs stale when semantic sources change; summaries are refreshed only by an explicit new run. Input/output validation and state checks belong to the framework. No repository command is executed by these adapters.

Local Codex and Claude adapters

codex-cli and claude-cli invoke installed CLIs for Discussion/synthesis proposals. agent doctor [--adapter ID] checks version/help without sending a model request. Configuration remains portable and requires no installed provider: use agent configure --adapter codex-cli --profile general --model default --timeout 120 and configure activity specializations as needed. Credentials/login stay with the provider; AIE never copies them into canonical records. default model omits the model flag. Profile is an AIE role instruction, not a vendor configuration file.

init . --interactive guides general/refine/analyze/summarize setup. --input-file supplies explicit UTF-8 answers without a terminal; missing/incomplete input refuses publication. init . also guides setup in a console when --name is omitted. Ordinary init --name TEXT remains noninteractive. Setup never calls a model.

Real runs use a private temporary directory, stdin context, fixed argument vectors, bounded streams and timeout. Source repository working directories are not supplied; tools/customizations are disabled and Codex uses read-only sandbox with no escalation. These are provider controls, not an OS sandbox guarantee. No permission bypass or silent executor retry/fallback is used. Essential identity/auth/proxy environment is forwarded privately; raw stderr/environment/credentials are not canonical evidence.

The framework assigns adapter identity/fixture=false and validates the complete typed proposal before publication. Transport/schema/auth/timeout failures leave the Work unchanged. RUN provenance records observed CLI version, configured role/model, duration, timeout and output digest/size. Prior RUN outputs travel with context as derived interpretations, not new verified observations. Explicit --activity avoids a model classification call; ambiguous classification can produce clarify surveys with options. No response can approve a DEC, answer human surveys, complete a Work or run repository commands. EPIC/conformance/state checks remain deterministic framework operations.

EPICs and derived Works

An EPIC is a Work coordinating other project Works. Create Works normally, then use epic configure WRK --mode results|decomposition --by NAME --reason TEXT and epic link EPIC CHILD --by NAME --reason TEXT. Children are important by default. The initial topology allows nested EPICs, one parent per child and no cycles. epic importance EPIC CHILD --optional|--important and epic unlink revise links with actor/reason and history. Delivered parents need explicit reopening first.

RESULTS waits for verified important children. An important CANCELLED child remains pending until scope/importance is reviewed. Optional children can remain open. DECOMPOSITION closes through normal human-reviewed Work completion without waiting for child execution; it never auto-completes. Empty important sets never auto-close.

epic authorize WRK --by NAME --reason TEXT --human-approved records explicit human delegation: the current aggregate condition is sufficient for this parent's criteria. Never infer or invent that approval. Scope/link/policy changes invalidate it. The framework still checks local questions, decisions, plans and evidence, without LLM. Automatic completion creates an owned ART receipt and records SYSTEM_EPIC origin, humanApproved=false and the actual policy authority. It does not invent direct human delivery approval or claim semantic verification of arbitrary prose criteria.

Lifecycle commands notify affected ancestors and return status/pending results to the requester. An important child reopening reopens RESULTS ancestors, retaining history; optional changes do not. Explicit EPIC reopening suspends automatic authority so replanning is possible; child-caused reopening preserves unchanged-scope authority. epic show/check/history inspects state. epic reconcile [WRK] --requester NAME --request-id KEY recovers missed propagation from files; repeated checks do not duplicate completion/receipts. Reads never invoke an adapter or perform transitions. Publication is per file; corrupt records and interrupted orphan publication may still need deliberate repair. Use public CLI/Verification lifecycle APIs for notification; low-level storage callers must explicitly reconcile after their writes.

Decisions and human authority

decision draft, decision update, decision show/list/history manage formal DECs. decision accept WRK DEC --by NAME --reason TEXT --human-approved records an explicit human approval. Agents MUST NOT infer or invent that approval. The flag is an audit attestation, not authentication or an OS permission grant. Rejected proposals remain in history. Use decision revise for a new draft based on a prior accepted/rejected decision; acceptance supersedes the prior accepted decision while retaining history. Accepted decisions cannot be silently edited. Use --by and --reason on changes.

Planning and adaptive execution

Use plan create WRK --title TEXT [--decision DEC], then plan step add for a lightweight plan. plan step update refines steps/dependencies; plan step status records OPEN, ACTIVE, BLOCKED, COMPLETED or CANCELLED. Dependencies must be completed before starting dependent steps. Completed steps require a result (--reason) and owned --evidence ART. Plan decisions must be accepted for execution.

The CLI records work and can apply validated fixture proposals; it does not execute repository commands. Observe results, reconsider hypotheses and replan explicitly when evidence changes. OODA is adaptive, not a mandatory four-stage pipeline. No autonomous repository executor, orchestrator, Git push/merge, worktree manager or custom workflow engine is implied.

plan status records the plan's state; plan history exposes previous snapshots. Record test/build/source revisions and commands in evidence rather than claiming success from a status label. Respect read-only repository policy and the OS sandbox.

Verification and closure

When the last required step completes, AIE consolidates its Plan and rechecks the Work's Plans. All required Plans completed, with no pending questions/surveys or draft DECs, completes the Work automatically. Criteria/results/evidence belong to the Plans/steps; no new Work-level checklist or model call is required. Completion records SYSTEM_PLANS origin, humanApproved=false and an owned receipt identifying the exact Plan revisions. Empty sets and explicit BLOCKED/CANCELLED states remain pending. EPIC policy/authorization is preserved.

Cancelled steps/Plans require explicit scope review: plan exclude WRK PLN [--step TSK] --by NAME --reason TEXT. This retains history and excludes only the reviewed content, without inventing a delivery or satisfying dependencies. work reconcile WRK --requester NAME --request-id KEY recovers missed coordination without duplicate completion. CLI mutations return state, pending Plans and EPIC effects. Reads do not transition state. New Plans after completion require explicit Work reopening; unchanged old Plans do not immediately reclose a reopened Work.

project validate / work validate check structure, references, revision chains and evidence integrity. work check reports mechanical readiness to close. It does not prove that prose acceptance criteria have semantically been satisfied.

For small inspection-only Works without Plans, work complete WRK --by NAME --summary TEXT --human-approved --criterion 1=ART-0001 records the human-reviewed criterion-to-evidence mapping. Supply one mapping per criterion, and either --integration PATH for canonical files updated or --no-integration-needed REASON. Address questions and finish/cancel plans first. Do not mark COMPLETED through a generic status change. Use disposable test data; never confuse a historical report with a test run performed now.

Update canonical code, tests, specs and documentation. There is no mandatory Lesson entity. work archive retains all files/history; work reopen --by NAME --reason TEXT allows new evidence and reorientation while retaining earlier completion records. Never delete history as housekeeping. Importing legacy agendas/lessons is deferred.

Portable files and errors

Work IDs are uppercase hexadecimal; child IDs are Work-local decimal identifiers. Discussion and new decision/plan prose use Markdown bodies with versioned YAML front matter. Use CLI mutations for IDs and references; human-authored prose remains portable. Revisions live beside their records in .history, with SHA-256 links. .local stores locks/backups and is not canonical state. Writes are atomic per file, not across all records; validation diagnoses interrupted cross-record publication. Preserve backups and repair deliberately, rather than silently dropping missing references.

Exit codes: 0 success, 1 unexpected I/O/runtime error, 2 invalid input, 3 missing resource, 4 validation/readiness failure. Read --help for exact command options.