250 lines
16 KiB
Markdown
250 lines
16 KiB
Markdown
# 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.
|
|
|
|
## Compatibility and protocol updates
|
|
|
|
Run `aie project compatibility --format json` before considering an update. `status`
|
|
includes a compatibility summary and the diagnostic command. The diagnostic is
|
|
read-only: it inspects actual canonical files and record revisions, without locks,
|
|
backups, model calls or migrations. It includes AIE completion receipts, while ignored
|
|
runs, local backups and ordinary artifact payloads are excluded. Use `project validate`
|
|
for integrity.
|
|
|
|
`protocol.json` separates `schemaVersion` (the manifest shape) from `protocolVersion`
|
|
(the engineering contract revision). A missing `protocolVersion` denotes the legacy
|
|
baseline contract 1. The report exposes the installed CLI release, supported contract
|
|
versions, format catalog, observed versions and missing defaulted Work fields.
|
|
Storage `schemaVersion` and narrative `documentVersion` remain independent.
|
|
|
|
States are `CURRENT`, `LEGACY_COMPATIBLE`, `UNSUPPORTED` and `INVALID`. The first two
|
|
are readable, return exit 0 and do not require migration. Unsupported or invalid
|
|
records return exit 4 with file-specific diagnostics. A newer manifest does not prove
|
|
that old records were converted. A missing optional field is not by itself a defect.
|
|
Compatibility is separate from structural validation and completion readiness.
|
|
|
|
Keep historical and COMPLETED Works in their original formats. The CLI reads older
|
|
supported representations and applies documented defaults in memory, preserving
|
|
IDs, approvals, evidence, completion provenance and content hashes. Never reopen or
|
|
rewrite a completed Work merely to materialize current fields, topics or surveys.
|
|
|
|
`aie onboard` refreshes the entry instructions and manifest, with backups, while
|
|
leaving Works, evidence and revision history unchanged. A newer unsupported manifest
|
|
or contract is refused rather than overwritten; use a compatible CLI. No required
|
|
migration is registered in this release. Future conversions must have an explicit
|
|
public command, scope, preview, backups and repeatable execution. Do not invent a
|
|
migration or inspect AIE source code to discover consumer update procedures; report
|
|
public-interface gaps with evidence instead.
|
|
|
|
## 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.
|