factory/vibe

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.