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>
This commit is contained in:
54
vibe/shareouts/2026-06-23-vibe-and-safe-env/README.md
Normal file
54
vibe/shareouts/2026-06-23-vibe-and-safe-env/README.md
Normal file
@@ -0,0 +1,54 @@
|
||||
[vibe](../../README.md) > [Shareouts](../README.md) > **2026-06-23 · Vibe & environnement sûr**
|
||||
|
||||
# Vibe & environnement sûr — ce qu'on a posé le 2026-06-23
|
||||
|
||||
> **Date :** 2026-06-23 · **Statut :** Actif · **Audience :** humains du lab Arcodange (lecteurs non spécialistes bienvenus)
|
||||
|
||||
> [!TIP]
|
||||
> **TL;DR**
|
||||
> - On a créé `vibe/`, la **base de connaissances pour agents IA**, et un `AGENTS.md` qui sert de carte de l'écosystème et de règles du jeu.
|
||||
> - On a écrit le **premier ADR** (la décision) et la **première PRD** (la spécification) d'un **environnement sûr de type production, en LOCAL uniquement**.
|
||||
> - On a ajouté un **guidebook de l'écosystème** : la carte « qui parle à qui » entre les dépôts `factory`, `tools` et `cms`.
|
||||
|
||||
## Ce qui a été fait
|
||||
|
||||
- **Le dossier `vibe/`** — un tronc de documentation pensé pour les agents IA qui travaillent sur le lab. Il range le *pourquoi* (ADR), le *quoi/quand* (PRD), le *ce-qu'on-a-trouvé* (investigations), le *comment-ça-s'emboîte* (guidebooks), le *comment-faire* (runbooks) et le *ce-qu'on-a-dit-aux-humains* (shareouts, comme cette page).
|
||||
- **Un `AGENTS.md`** — la carte de l'écosystème et le règlement : conventions de nommage, gestion des secrets, style de documentation, règles de branches et de PR. Un agent qui débarque le lit en premier.
|
||||
- **Le premier ADR** — [« Safe, production-like environment »](../../ADR/0001-safe-prod-like-environment.md) : la décision actée, figée comme un fait historique.
|
||||
- **La première PRD** — [« Safe, production-like environment »](../../PRD/safe-prod-like-environment/README.md) : la spécification détaillée (problème, objectifs, périmètre, critères de succès, stratégie de tests).
|
||||
- **Un guidebook de l'écosystème** — [Lab ecosystem](../../guidebooks/lab-ecosystem/README.md) : la carte de bout en bout de `factory` + `tools` + `cms`, et de la convention `<app>` qui les relie.
|
||||
|
||||
## Pourquoi ça compte
|
||||
|
||||
Aujourd'hui, tester une modification revient trop souvent à la tester **directement sur ce qui tourne pour de vrai**. Or « pour de vrai » ici, ce sont des services qui comptent :
|
||||
|
||||
- le **mail `arcodange.fr`** (Zoho : MX, SPF, DKIM, DMARC, alias) — une fausse manip et des courriels se perdent ;
|
||||
- le **CMS** (le site public `arcodange.fr`) ;
|
||||
- l'**ERP** et les autres applications du lab.
|
||||
|
||||
Sans filet, chaque essai est un pari sur la production. L'idée posée ce jour-là : se donner un **bac à sable fidèle à la prod** où l'on peut casser, recommencer et valider **sans jamais toucher** aux services réels.
|
||||
|
||||
## Décision clé
|
||||
|
||||
Un **environnement local et reproductible**, isolé de la production :
|
||||
|
||||
- un cluster **k3d** local, alimenté par **3 VMs arm64** qui rejouent la topologie des 3 Raspberry Pi ;
|
||||
- une **frontière d'isolation stricte** : l'environnement de test ne peut ni lire ni écrire dans la prod (pas d'accès au mail réel, au DNS public, aux bases de production) ;
|
||||
- un **périmètre volontairement limité au logiciel** : les niveaux **matériel** (les Pi physiques) et **cloud** (Cloudflare, OVH, GCS) restent **hors périmètre** pour cette première itération.
|
||||
|
||||
Autrement dit : on reproduit la *pile applicative*, pas la *quincaillerie* ni les *comptes cloud*. C'est le bon compromis pour tester vite et sans risque.
|
||||
|
||||
## Liens
|
||||
|
||||
- ADR — [Safe, production-like environment](../../ADR/0001-safe-prod-like-environment.md)
|
||||
- PRD — [Safe, production-like environment](../../PRD/safe-prod-like-environment/README.md)
|
||||
- Guidebook — [Lab ecosystem](../../guidebooks/lab-ecosystem/README.md)
|
||||
|
||||
## Pour aller plus loin
|
||||
|
||||
Ce dossier peut accueillir, plus tard, des supports complémentaires :
|
||||
|
||||
- un **deck** de présentation des slides ;
|
||||
- un **mp4** narré — capture `ffmpeg`/Playwright, ou un explainer produit avec le skill `documentary-video`.
|
||||
|
||||
Il suffira de les déposer ici, à côté de ce `README.md`, et d'ajouter une ligne dans l'[index des shareouts](../README.md).
|
||||
56
vibe/shareouts/README.md
Normal file
56
vibe/shareouts/README.md
Normal file
@@ -0,0 +1,56 @@
|
||||
[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.
|
||||
Reference in New Issue
Block a user