Gabriel Radureau
3961914613
Records the decision to extend the <app> join key with a second coordinate <env>, governed by an elision rule (env=prod elides → every existing app's derived names are byte-identical and its tofu plan is a no-op; non-prod envs take the <app>-<env> suffix, with the Postgres owner role staying snake-case <app>_<env>_role). Motivated by the ERP's incoming write-capable AI-agent skill: it needs an in-cluster sandbox instance (erp-sandbox) with a prod-like Dolibarr API + isolated database to rehearse writes before a human promotes them to prod. The ADR reconciles this against ADR-0001 honestly — ADR-0001 rejected an in-cluster sandbox for INFRA-change rehearsal (shared fleet-wide control planes); ADR-0002 operates one layer up where the agent's only reach is the app's HTTP API against an isolated DB, so the fleet blast radius is not in scope. The two are complementary; ADR-0002 does not supersede ADR-0001. Also: - vibe/ADR/README.md: index row for 0002 + Last Updated 2026-06-25 - PRD safe-prod-like-environment README: bidirectional back-link to ADR-0002 on the Adjacent line + Last Updated 2026-06-25 Authored via the ADR Scribe persona, validated via the Continuity Warden checklist (no-tombstone, breadcrumb, MADR-lite sections, dead-link scan, bidirectional links). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
vibe/ — Arcodange Knowledge Base
You-are-here: the root of the vibe/ knowledge tree — the front door for every doc agents write and read.
Up: factory / AGENTS.md
Status: Active Last Updated: 2026-06-23
What is vibe/?
vibe/ is the knowledge base dedicated to LLM agents working on the Arcodange lab. It collects the why (ADRs), the what/when (PRDs), the what-we-found (investigations), the how-it-fits-together (guidebooks), the how-to-do-it (runbooks), and the what-we-told-humans (shareouts). Everything here is written in English — the single exception is shareouts handouts, which are FRENCH. Operating rules (no-tombstone, mermaid prefs, tree-docs, ADR/PRD/investigation conventions, PR crosslinking, language policy) are defined authoritatively in AGENTS.md; this page summarizes them and points there.
Folder map
| Folder | When to use it | Status |
|---|---|---|
| ADR | Recording an architecture decision (MADR-lite; body immutable once Accepted). Canonical home going forward. | ⬜ |
| PRD | Specifying a product/project: Problem → … → QA strategy → STATUS.md (mandatory, kept current). |
⬜ |
| investigations | Capturing a finding/analysis — single INV-NNN-slug.md, or stub + notebooks when data-heavy. |
⬜ |
| guidebooks | Mapping a component or the ecosystem as navigable tree-docs (the lab cartography). | ⬜ |
| runbooks | Documenting an operational procedure step-by-step with [AGENT] / [HUMAN] markers. |
⬜ |
| shareouts | Producing handouts/presentations for humans (FRENCH). | ⬜ |
Status legend: ✅ done · 🟡 beta · 🔴 critical · ⚠️ known issue · ❌ disabled · ⬜ not started.
Conventions at a glance
- No-tombstone rule (foremost) — write each file as currently true; never leave "previously X, now Y", changelogs, or "updated to …" notes. Git history is the audit trail. Only exception: a forward-looking
> [!CAUTION]about a live risk. - Breadcrumb spine — every non-root file starts with a breadcrumb: ancestors as relative links, current page bold-unlinked, separator
>. This root has no breadcrumb (it uses the you-are-here + up-link above instead). - README hub per folder — each folder's
README.mdis an index table of its children (link + one-line summary + status), sorted by importance/sequence. - Bidirectional links — if A references B as related, B references A. Use descriptive link text (never "here"/"this").
- Mermaid prefs —
theme base/forestinit directive; legibleclassDefpalette (dark fills + light text);<br>not\n; leading space before slash-labels; validate with the Mermaid MCP; a numbered ordered list restating the flow after every diagram. - GitHub alert legend —
[!NOTE]info/forward-looking ·[!TIP]aside ·[!IMPORTANT]inherent constraint ·[!WARNING]degraded-but-working ·[!CAUTION]data-loss/breaking. - Status emoji legend — ✅ done · 🟡 beta · 🔴 critical · ⚠️ known issue · ❌ disabled · ⬜ not started.
- Language policy — English throughout
vibe/; FRENCH only for shareouts handouts.
Authority for all of the above: AGENTS.md.
Maintenance policy
- Adding a page → also add its row to the parent folder's
README.mdindex table. - Keep links bidirectional → when you link A→B, add B→A.
- Stamp
Last Updated:at each tree root (this file and every guidebook/big-PRD root) after any structural change. - Never tombstone → edit content in place; let git carry the history.
- Guidebook coupling → changing a documented component means updating its guidebook page in the same change.
- PR crosslinks → every PR references the ADR/PRD it advances; that ADR's References and the PRD's
STATUS.mdlink back.
Cohort + workflow (recap)
Docs here are produced by a cohort of persona subagents — Lab Cartographer, ADR Scribe, PRD Architect, Runbook Engineer, Investigator, Diagram Smith, Continuity Warden — spawned via the Agent tool or a Workflow. The recommended pipeline for substantial contributions is Scaffold → Author → Validate → Review → Assemble. Full descriptions and responsibilities live in AGENTS.md.