arcodangeandClaude Fable 5
dd7b683944
Agents landing in this repo had no entry point: no AGENTS.md, and the backlog (erp#38-57 on 6 dated milestones, gateway#1-2, factory#22) was only discoverable from the PRD STATUS in the factory repo. This seeds the repo-root orientation map: where the work comes from (resume protocol: top unblocked issue of the earliest open milestone, gitea MCP pointers, owner gotcha for telegram-gateway), the repo map, the operating rules (trunk/worktrees, read-only prod, sandbox+promote gate, append-only ledger, anti-hallucination contract pointers). Advances erp#38 (AGENTS.md seed; the fleet/ scaffold and the full fleet section remain in #38's scope). Co-Authored-By: Claude Fable 5 <[email protected]>
36 lines
4.3 KiB
Markdown
36 lines
4.3 KiB
Markdown
# 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/` | atom registry, class skeletons, golden sets — **not yet landed**, tracked by [erp#38](https://gitea.arcodange.lab/arcodange-org/erp/issues/38) |
|
||
|
||
## 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.
|
||
|
||
## 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.
|