feat(fleet): scaffold the atom registry — classes, contract, worked example, AGENTS.md section
Closes erp#38 deliverables: fleet/ layout, atom.yaml schema documented in fleet/README.md, 7 class skeletons per the PRD agent-catalog, invoice-extract as the worked example (contract only — implementation is erp#40), golden/ + profile/ stubs, AGENTS.md Fleet section with freshness fixes (fleet/ no longer "not yet landed"). Co-Authored-By: Claude Fable 5 <[email protected]>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,98 @@
|
||||
# fleet/ — the atom registry
|
||||
|
||||
The fleet is Arcodange's AI back-office: narrow agents ("atoms") that operate the
|
||||
Dolibarr ERP's daily admin & accounting under the
|
||||
[AI back-office PRD](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md).
|
||||
This directory is the **registry** — the versioned source of truth for what the
|
||||
fleet may do. **An atom absent from the registry does not run.** Contract semantics
|
||||
come from the PRD [atom contract](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md#atom-contract);
|
||||
file syntax from the PRD [document surface](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-catalog.md#the-document-surface-agents-read).
|
||||
|
||||
## What an atom is
|
||||
|
||||
One narrow capability (classify, extract, validate, record, reconcile, report,
|
||||
remind) with a **strict I/O contract** and **deterministic validators around it**.
|
||||
The LLM proposes, code disposes: formats, arithmetic, checksums, dedupe and
|
||||
referential integrity are enforced by validators, and a model output that fails
|
||||
validation is **quarantined, never auto-corrected**. Workflows are compositions of
|
||||
atoms with explicit gates — never one prompt that "does the accounting".
|
||||
|
||||
Each atom lives in `fleet/atoms/<atom>/`:
|
||||
|
||||
| File | Role |
|
||||
| --- | --- |
|
||||
| `atom.yaml` | the registry entry — the contract (schema below) |
|
||||
| `prompt.md` | thin runtime prompt, ≤ ~40 lines, extends exactly one class skeleton; **no business rules** (rules live in `fleet/profile/` and in validators) |
|
||||
| `scripts/` | the deterministic implementation: runners, validators, scoring hooks |
|
||||
|
||||
Folder name = atom name = registry `name` — the house `<app>` join-key discipline
|
||||
applied to atoms.
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
fleet/
|
||||
├── README.md # this file: registry doc + atom.yaml schema
|
||||
├── classes/ # the 7 prompt skeletons (PRD agent catalog)
|
||||
│ ├── sentinel.md
|
||||
│ ├── extractor.md
|
||||
│ ├── erp-scribe.md
|
||||
│ ├── deterministic-controller.md # no-LLM by design
|
||||
│ ├── analyst-writer.md
|
||||
│ ├── researcher.md
|
||||
│ └── knowledge-archivist.md
|
||||
├── atoms/
|
||||
│ └── invoice-extract/ # T02 — the worked example (contract only; implementation = erp#40)
|
||||
│ ├── atom.yaml
|
||||
│ ├── prompt.md
|
||||
│ └── scripts/
|
||||
├── golden/ # per-atom golden sets — land with erp#39
|
||||
└── profile/ # fiscal.yaml + calendar.yaml + ADC register — land with erp#54
|
||||
```
|
||||
|
||||
## `atom.yaml` — the contract, field by field
|
||||
|
||||
Per the PRD [atom contract](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md#atom-contract):
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `name`, `version` | Identity. Folder name = `name`. `version` bumps on **any** behavioral change (prompt, model, validator) — a bump re-triggers the atom's golden-set evals. |
|
||||
| `input_schema` / `output_schema` | JSON Schema for the atom's I/O; enforced at runtime (constrained decoding where the model tier supports it). |
|
||||
| `invariants` | Deterministic post-conditions checked by code after every run (e.g. `HT + TVA == TTC ± 0.01`). A failed invariant quarantines the output — refuse, never repair. |
|
||||
| `side_effect_class` | `read` · `draft` · `write-sandbox` · `write-prod` · `outbound` — drives which gates and credentials apply, per the PRD [environment posture table](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md#environments--sandbox-vs-production). |
|
||||
| `idempotency_key` | How a replay is recognized (e.g. supplier + `ref_supplier` + TTC) — a second run with the same key must be a no-op. |
|
||||
| `autonomy` | The **earned** level (A0–A3 on the [autonomy ladder](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md#the-autonomy-ladder)) + a pointer to the eval evidence that justifies it. |
|
||||
| `model_policy` | Preferred tier, fallbacks, escalation rule, per the PRD [model fleet](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/model-fleet.md); closed per-atom by routing-bench evidence (erp#45 for the first atoms). |
|
||||
| `eval_ref` | Where the golden set + scoring script live (`fleet/golden/<atom>/`). |
|
||||
|
||||
Two registry conveniences beyond the PRD contract fields bind the entry to the rest
|
||||
of the surface: `class` (which `fleet/classes/<class>.md` skeleton the prompt
|
||||
extends) and `task` (the PRD [task-inventory](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/task-inventory.md)
|
||||
id the atom serves).
|
||||
|
||||
The worked example is [`atoms/invoice-extract/atom.yaml`](atoms/invoice-extract/atom.yaml)
|
||||
(T02) — contract only; its implementation is
|
||||
[erp#40](https://gitea.arcodange.lab/arcodange-org/erp/issues/40).
|
||||
|
||||
## How an atom graduates
|
||||
|
||||
Autonomy is **earned per atom, never assumed**. The levels (A0 manual → A1 prepare
|
||||
→ A2 rehearse + gate → A3 autonomous + audit) are defined on the PRD
|
||||
[autonomy ladder](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md#the-autonomy-ladder);
|
||||
promotion and demotion are mechanical, per the PRD
|
||||
[autonomy promotion gates](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/qa-strategy.md#autonomy-promotion-gates)
|
||||
(golden-set evals, unedited-approval streaks, incident demotion — the bars live
|
||||
there, not here). The earned level and its evidence are recorded in the atom's
|
||||
`autonomy` field: a promotion is a PR that changes that field with the evidence
|
||||
linked, verified per the QA strategy's independent-verification rule.
|
||||
|
||||
## Conventions
|
||||
|
||||
- **English** for all agent-facing files (house language policy).
|
||||
- **Same-change freshness**: a change to an atom that leaves its
|
||||
`atom.yaml` / `prompt.md` stale is an incomplete change.
|
||||
- **One capability per file**; YAML/frontmatter over prose for anything a machine
|
||||
parses.
|
||||
- Environment rules (trunk hygiene, read-only prod, sandbox-first writes, promote
|
||||
gate) are the repo-wide ones: [`AGENTS.md`](../AGENTS.md) operating rules +
|
||||
[`dolibarr-sandbox-write` SKILL.md](../.claude/skills/dolibarr-sandbox-write/SKILL.md).
|
||||
Reference in New Issue
Block a user