arcodange-org/erp
1
0
Fork 0
Code Issues 18 Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
6b576931b6d7db652e189cb77c5b25c0181a2491
erp/AGENTS.md
T
arcodangeandClaude Fable 5 96c594e0ce 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]>
2026-07-15 18:38:08 +02:00

45 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# erp — Dolibarr ERP & the AI back-office fleet
This repo runs Arcodange's **Dolibarr 22.0.4 ERP** (the company's book of record) and hosts the tooling + AI-agent skills that operate its daily admin & accounting. Deployed by the factory ArgoCD app-of-apps: **prod** at `erp.arcodange.lab`, **iso-prod sandbox** at `erp-sandbox.arcodange.lab`. Ecosystem front door: [factory AGENTS.md](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/AGENTS.md).
## Where the work comes from — the backlog
The [AI back-office PRD](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/README.md) is decomposed into **self-contained issues** on dated milestones. Each issue body carries its context, deliverables, acceptance criteria, dependencies and PRD links — no conversation history needed.
- **Resume protocol: pick the top unblocked issue of the earliest open [milestone](https://gitea.arcodange.lab/arcodange-org/erp/milestones)** (P1 flagship → P2 e-invoicing *hard 2026-09-01* → P3 standing fleet → ledger compliance → P4 money loops → P5 fiscal).
- From a session: `ToolSearch select:mcp__gitea__list_issues,mcp__gitea__issue_read`, then owner `arcodange-org`, repo `erp`. Related backlogs: [telegram-gateway issues](https://gitea.arcodange.lab/arcodange/telegram-gateway/issues) (owner `arcodange`, **not** arcodange-org) and [factory#22](https://gitea.arcodange.lab/arcodange-org/factory/issues/22) (ADR tracking).
- Full phase tracker + backlog map: the PRD [STATUS.md](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/STATUS.md).
## Map
| Path | What |
| --- | --- |
| `chart/` | Helm chart (prod + sandbox overlay), backup CronJob, before-start SQL |
| `ops/` | `sandbox/sandbox-lifecycle.sh` (iso-prod refresh), `backup/` (offsite db+docs, restore) |
| `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/` | 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
- **Trunk is reserved for the user.** Work in a worktree under `.claude/worktrees/<slug>/` on an `arcodange/<slug>` branch. This forge is **Gitea** — use the `mcp__gitea__*` tools for PRs/issues; `gh` fails silently.
- **Prod is read-only for agents** (`ai_agent` key from `.claude/skills/dolibarr/.env`, mode 600). Beware the `voir_tous` ACL trap: a missing permission returns empty lists, not errors.
- **Writes rehearse on the sandbox first** (`ai_agent_sandbox`, host-guarded — structurally cannot reach prod), then reach prod only through the human-gated promote flow (`arcodange promote plan|apply`, prod key ENV-only + explicit confirm) — [ADR-0003](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/ADR/0003-sandbox-state-lifecycle.md).
- **Production is an append-only ledger**: create → validate → pay → avoir; never mutate or delete a validated document, never fabricate a ref Dolibarr owns. Full grammar + anti-hallucination write contract (provenance anchors, fresh-feed corroboration, refuse-never-repair): PRD [compliance](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/compliance.md) + [agent-architecture](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/PRD/ai-back-office/agent-architecture.md).
- Sandbox state is disposable: `bin/arcodange sandbox checkpoint {status|refresh|provision|relink-env}` (refresh re-seeds iso-prod and wipes the write agent → re-provision, human login). Anything irreversible-by-design is trialed on a checkpoint first.
- 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 A0–A3 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 A0–A3, 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.
Reference in New Issue View Git Blame Copy Permalink