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:
2026-07-15 18:38:08 +02:00
co-authored by Claude Fable 5
parent 3ad2d1df74
commit 96c594e0ce
14 changed files with 536 additions and 1 deletions
+9 -1
View File
@@ -19,7 +19,7 @@ The [AI back-office PRD](https://gitea.arcodange.lab/arcodange-org/factory/src/b
| `bin/arcodange` | operational CLI — read prod (invoices, payments, TVA, bank, templates, snapshot), sandbox writes, gated promote |
| `.claude/skills/` | the skill catalog; each `SKILL.md` frontmatter carries its **Use when… / SKIP for…** triggers — read them before reinventing |
| `test/` | Playwright provisioning POCs (sandbox write agent `ai_agent_sandbox`, rights in `provisionSandbox.ts` WRITE_IDS) |
| `fleet/` | atom registry, class skeletons, golden sets — **not yet landed**, tracked by [erp#38](https://gitea.arcodange.lab/arcodange-org/erp/issues/38) |
| `fleet/` | the AI-agent fleet — atom registry + `atom.yaml` schema ([fleet/README.md](fleet/README.md)), class skeletons ([fleet/classes/](fleet/classes/)), worked example `invoice-extract`; golden sets + fiscal profile are stubs ([erp#39](https://gitea.arcodange.lab/arcodange-org/erp/issues/39), [erp#54](https://gitea.arcodange.lab/arcodange-org/erp/issues/54)) |
## Operating rules for agents
@@ -31,6 +31,14 @@ The [AI back-office PRD](https://gitea.arcodange.lab/arcodange-org/factory/src/b
- Bank feeds (Qonto/Wise) and the Zoho mailbox are **read-only by construction**; no agent ever moves money.
- **Doc freshness.** Docs describe intent; the PRD STATUS + git describe reality. Before acting on any versionable claim (a path exists, a flag's value, a status emoji), verify in trust order: **live system > code/git log > [PRD STATUS](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/STATUS.md) > PRD leaves > memories**. A PR that makes a documented claim false updates that doc **in the same PR**; whoever closes a milestone follows the QA-gated [closure protocol](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/STATUS.md) — the QA gate is held by an **independent context-free subagent prompted to refute** (the closer never self-certifies) → flip STATUS → truth-pass docs → deprecation grep → fresh-reader smoke test — before the milestone closes.
## Fleet
- **Atom registry**: [`fleet/README.md`](fleet/README.md) — what an atom is, the `atom.yaml` contract schema field by field, the `fleet/` layout. An atom absent from the registry does not run.
- **Class skeletons**: [`fleet/classes/`](fleet/classes/) — the 7 prompt skeletons per the PRD [agent catalog](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-catalog.md#agent-classes); every atom's `prompt.md` extends exactly one, and prompts carry **no business rules** (those live in `fleet/profile/` + validators).
- **Environment rules**: the [operating rules](#operating-rules-for-agents) above + [`.claude/skills/dolibarr-sandbox-write/SKILL.md`](.claude/skills/dolibarr-sandbox-write/SKILL.md) (the host-guarded sandbox write path and its promote gate).
- **Autonomy ladder**: levels A0A3 in the PRD [hub](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md#the-autonomy-ladder); promotion/demotion per the PRD [qa-strategy gates](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/qa-strategy.md#autonomy-promotion-gates).
- **Graduation**: an atom earns autonomy through its golden-set evals and unedited-approval streaks — the earned level + eval evidence live in its `atom.yaml` `autonomy` field, and a promotion is a PR changing that field with the evidence linked.
## Before building anything
Read the PRD hub (5 min) — problem, autonomy ladder A0A3, architecture, agent catalog. Then your issue. Then the SKILL.md of anything you touch. A change that leaves its `SKILL.md` stale is an incomplete change.