arcodange-org/erp
1
0
Fork 0
Code Issues 18 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: AGENTS.md — orientation + backlog discovery for agents #58

Merged
arcodange merged 3 commits from arcodange/agents-md-backlog into main 2026-07-11 20:21:22 +02:00
Conversation 0 Commits 3 Files Changed 1
+35
1 changed files with 35 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit dd7b683944 - Show all commits
AGENTS.md
+35
View File
@@ -0,0 +1,35 @@
# 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.