arcodange-org/factory
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(vibe): bootstrap vibe/ knowledge tree + ecosystem AGENTS.md

Browse Source 
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:
Gabriel Radureau
2026-06-23 11:52:37 +02:00
parent 827af6b392
commit 7647a68cdc
25 changed files with 1878 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
vibe/runbooks/README.md Normal file
View File

@@ -0,0 +1,60 @@
[vibe](../README.md) > **Runbooks**
# Runbooks
> **Status:** Active (conventions + template only — first concrete runbook lands with PRD Phase 1)
> **Last Updated:** 2026-06-23
> **Related:** [vibe guidebooks](../guidebooks/README.md) · [vibe shareouts](../shareouts/README.md) · [FRENCH human runbooks under doc/runbooks](../../doc/runbooks/README.md)
## What lives here
`vibe/runbooks/` holds **agent-oriented operational runbooks, written in English** (this tree is for LLM agents). Each runbook is an ordered procedure where every step is tagged with an actor marker:
- **`[AGENT]`** — read-only or otherwise safe steps an agent may execute autonomously (inspecting state, dry-runs, generating files, running tests in a sandbox).
- **`[HUMAN]`** — production-mutating steps that require **explicit human approval** before they run (anything that writes to live infrastructure, deletes data, or changes the trunk).
The marker is load-bearing: it tells an agent reading the runbook exactly where its autonomy ends and where it must stop and hand control back to a human.
```mermaid
%%{init: {'theme': 'base'}}%%
flowchart LR
classDef agent fill:#059669,stroke:#047857,color:#fff
classDef human fill:#dc2626,stroke:#b91c1c,color:#fff
classDef gate fill:#7c3aed,stroke:#6d28d9,color:#fff
A["[AGENT] safe steps<br>(inspect, dry-run, generate)"]:::agent --> G{"approval<br>gate"}:::gate --> H["[HUMAN] prod-mutating steps<br>(explicit approval required)"]:::human
```
1. An agent executes the `[AGENT]`-tagged steps on its own — these only read state or act inside a sandbox.
2. When the procedure reaches a prod-mutating step, the agent stops at an approval gate.
3. A human reviews and approves; only then do the `[HUMAN]`-tagged steps run against live infrastructure.
## Not the same as `doc/runbooks`
> [!IMPORTANT]
> There are **two** runbook collections in this lab, and they serve different readers — do not merge them.
>
> | Collection | Reader | Language | Step markers |
> |---|---|---|---|
> | **`vibe/runbooks/`** (this folder) | LLM agents | English | `[AGENT]` / `[HUMAN]` |
> | **[`doc/runbooks/`](../../doc/runbooks/README.md)** | Human operators | French | prose procedures |
>
> The canonical, human-facing operator procedures (e.g. [Nouvelle application web](../../doc/runbooks/new-web-app/README.md)) live in French under `doc/runbooks/`. This folder is the agent-facing mirror: same operational reality, written so an autonomous agent can execute the safe parts and gate the dangerous ones.
## Index
| Runbook | Summary | Status |
|---|---|---|
| [_template](_template.md) | Skeleton for new agent-oriented runbooks (`[AGENT]`/`[HUMAN]` markers, copy-paste commands, verification + rollback) | ✅ Active |
> [!NOTE]
> The first **concrete** runbook — a local sandbox game-day for the safe prod-like environment — ships with **PRD Phase 1** ([safe-prod-like-environment PRD](../PRD/safe-prod-like-environment/README.md)). Until then this folder holds the conventions and the template only.
## Rules to contribute
1. **Start from [`_template.md`](_template.md).** Copy it, rename to `kebab-case.md`, fill every section, then add a row to the index table above.
2. **Tag every procedure step** `[AGENT]` or `[HUMAN]`. When in doubt, tag it `[HUMAN]` — over-gating is safe, under-gating is not.
3. **Use the `tree-docs` skill** and keep the breadcrumb spine: first line is the breadcrumb trail, ancestors as relative links, current page bold-unlinked, separator ` > `.
4. **README hub stays current** — every new runbook gets an index row here with a one-line summary and status.
5. **Bidirectional links.** If a runbook references a guidebook, ADR, or the French operator runbook, link back from there too. Use descriptive link text.
6. **Commands are copy-paste ready** — put them in fenced ```bash blocks, with the `[HUMAN]`/`[AGENT]` marker on the step that owns them.
7. **Status legend.** ✅ done · 🟡 beta · 🔴 critical · ⚠️ known issue · ❌ disabled · ⬜ not started.