Files

Gabriel Radureau 7647a68cdc docs(vibe): bootstrap vibe/ knowledge tree + ecosystem AGENTS.md

Add a root AGENTS.md (ecosystem map of factory/tools/cms + agent operating
rules + the persona cohort & workflow) and a new vibe/ knowledge base for LLM
agents, modeled on tree-docs conventions and the factory house style.

vibe/ folders (each with a README hub + contribution rules):
- ADR/      optimized MADR-lite; canonical home going forward (doc/adr stays historical)
- PRD/      one subfolder per PRD, mandatory STATUS.md, QA strategy for big ones
- investigations/  single INV-NNN-slug.md, or stub + folder w/ notebooks
- guidebooks/      tree-docs maps; lab-ecosystem guidebook of factory+tools+cms
- runbooks/        [AGENT]/[HUMAN] step procedures (EN; doc/runbooks stays FR)
- shareouts/       dated FR handouts (decks/mp4)

Seed content (first ADR + PRD): a safe, production-like environment to rehearse
risky changes and recovery without touching real prod — local-only sandbox
(k3d + arm64 VMs) with a hard prod/sandbox isolation boundary. Includes
INV-001 (prod blast-radius couplings), the ecosystem guidebook, and a FR shareout.

Conventions enforced: no-tombstone rule, breadcrumb spine, bidirectional
cross-links, theme:base mermaid (MCP-validated) + ordered-list-after-diagram.
Built with a Workflow + persona cohort; 24 files, zero dead links.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-23 11:52:37 +02:00

4.4 KiB

Raw Blame History

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.md is 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/forest init directive; legible classDef palette (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.md index 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.md link 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.

4.4 KiB Raw Blame History