first
This commit is contained in:
@@ -0,0 +1,278 @@
|
||||
# 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.
|
||||
|
||||
The current entry contract is 2 and advertises DF open-agenda import. Contract 1
|
||||
projects remain readable without Work migration. An import-enabled manifest needs
|
||||
contract 2 and the `discussion-import` capability; older CLIs must be updated before
|
||||
reading it. Refresh entry files with `onboard` after compatibility inspection,
|
||||
preserving historical Works and their approvals.
|
||||
|
||||
## 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.
|
||||
|
||||
Creating a Plan from a DRAFT decision promotes it automatically. This deterministic
|
||||
framework action needs no LLM or preceding `decision accept` command. It records
|
||||
`origin: SYSTEM_PLAN`, the causal `planId`, actor `system:planning` and
|
||||
`humanApproved: false`, preserving history and any supersession. It is distinct
|
||||
from the explicit human-attestation route above. Drafts still need nonblank context,
|
||||
approach and rationale; rejected/superseded decisions remain invalid Plan inputs.
|
||||
|
||||
## 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.
|
||||
|
||||
`plan create --decision DEC` promotes its referenced drafts before returning the
|
||||
new Plan. Already accepted decisions are unchanged. Inputs are validated together
|
||||
under the project lock; ordinary publication failures roll back promotions.
|
||||
Crash-interrupted publication may still need deliberate repair; use `work validate`
|
||||
to inspect causal Plan links and revision history. `plan update` does not promote
|
||||
drafts. Historical human approvals remain readable and are never rewritten into
|
||||
system approvals. New system-promotion records require a CLI with this capability.
|
||||
|
||||
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. `import discussion --source ID=PATH` previews
|
||||
DF DSCs with AGDs open; repeat sources for a multi-project umbrella and use
|
||||
`--target SOURCE=TEXT` for target descriptions. Apply only with `--apply --expect`
|
||||
using the returned preview fingerprint. Source paths are caller-relative; source
|
||||
IDs remain stable for reimport. Whole agenda text and original evidence are kept
|
||||
in one OPEN Work per source+DSC, without LLM calls or source edits. Identical imports
|
||||
are skipped and changed inputs require review without overwriting. Prepared Works
|
||||
publish individually; after partial publication, preview again to resume without
|
||||
duplicates. Closed agendas, DECs, Plans and Lessons are not imported.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user