Gabriel Radureau
7647a68cdc
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>
57 lines
3.4 KiB
Markdown
57 lines
3.4 KiB
Markdown
[vibe](../README.md) > **Shareouts**
|
|
|
|
# Shareouts
|
|
|
|
> **Status:** Active
|
|
> **Last Updated:** 2026-06-23
|
|
> **Related:** [vibe guidebooks](../guidebooks/README.md) · [vibe runbooks](../runbooks/README.md)
|
|
|
|
## What a shareout is
|
|
|
|
A **shareout** captures something substantial that was **done or seriously considered** — the outcome of an ADR, a PRD, or an investigation — and packages it as a **human-facing handout** you can hand to a person to explain what happened and why it matters.
|
|
|
|
Where guidebooks are the standing reference map and runbooks are the procedures, a shareout is a moment-in-time communication artifact: "here is the thing we built / decided / explored, told for humans."
|
|
|
|
```mermaid
|
|
%%{init: {'theme': 'base'}}%%
|
|
flowchart LR
|
|
classDef src fill:#2563eb,stroke:#1e40af,color:#fff
|
|
classDef proc fill:#059669,stroke:#047857,color:#fff
|
|
classDef store fill:#7c3aed,stroke:#6d28d9,color:#fff
|
|
WORK["Substantial work<br>(ADR / PRD / investigation)"]:::src --> SO["Shareout<br>(dated handout folder)"]:::proc --> HUM["Humans<br>(read .md, deck, watch .mp4)"]:::store
|
|
```
|
|
|
|
1. Some substantial work lands — an ADR is decided, a PRD phase ships, an investigation concludes.
|
|
2. It is packaged into a dated shareout folder holding the human-facing handouts.
|
|
3. Humans consume the handout: a Markdown summary, a slide deck, and optionally a narrated video.
|
|
|
|
## Convention: one dated subfolder per shareout
|
|
|
|
> [!IMPORTANT]
|
|
> Each shareout lives in **its own dated subfolder** named `YYYY-MM-DD-slug/`. The folder holds the human-facing handouts for that shareout: `.md` summaries, decks, and an optional `.mp4`.
|
|
|
|
The handouts inside a shareout folder can include:
|
|
|
|
- **`.md` summaries** — the written walkthrough (the folder's `README.md` is the front door).
|
|
- **Decks** — slides for presenting the work.
|
|
- **Optional `.mp4`** — `ffmpeg` compilations of screenshots, [Playwright](../../ansible/arcodange/factory/README.md) captures, or a narrated explainer produced with the `documentary-video` skill.
|
|
|
|
> [!NOTE]
|
|
> **Handouts are written in FRENCH.** The audience is humans, and the lab's human-facing audience is French-speaking. (This is the deliberate exception to the otherwise-English `vibe/` tree, which exists for LLM agents.)
|
|
|
|
## Index
|
|
|
|
| Shareout | What it covers | Status |
|
|
|---|---|---|
|
|
| [2026-06-23 · Vibe & safe-env](2026-06-23-vibe-and-safe-env/README.md) | Mise en place du tronc `vibe/` (guidebooks, runbooks, shareouts) et le PRD de l'environnement « safe prod-like » | ✅ Active |
|
|
|
|
## Rules to contribute
|
|
|
|
1. **One dated folder per shareout** — `YYYY-MM-DD-slug/`, kebab-case slug, ISO date. Never dump loose files at this level.
|
|
2. **Folder `README.md` is the front door** — it carries the breadcrumb, a TL;DR, and links to every handout in the folder (deck, video, sub-summaries).
|
|
3. **Handouts in French** — the audience is human. (Reminder: the rest of `vibe/` is English for agents.)
|
|
4. **Add an index row here** for every new shareout, with a one-line French summary and status, newest at the top.
|
|
5. **Use the `tree-docs` skill** for the breadcrumb spine and the per-folder README hub; use the `documentary-video` skill when a shareout warrants a narrated `.mp4`.
|
|
6. **Bidirectional links** — if a shareout points to an ADR/PRD/guidebook, link back from there. Descriptive link text only.
|
|
7. **Status legend.** ✅ done · 🟡 beta · 🔴 critical · ⚠️ known issue · ❌ disabled · ⬜ not started.
|