factory/vibe/runbooks/README.md

vibe > Runbooks

Runbooks

Status: Active (conventions + template only — first concrete runbook lands with PRD Phase 1) Last Updated: 2026-06-23 Related: vibe guidebooks · vibe shareouts · FRENCH human runbooks under doc/runbooks

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.

%%{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/	Human operators	French	prose procedures

The canonical, human-facing operator procedures (e.g. Nouvelle application web) 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	Skeleton for new agent-oriented runbooks ([AGENT]/[HUMAN] markers, copy-paste commands, verification + rollback)	✅ Active
Set up a new tool	Add a platform component to the tools repo so ArgoCD deploys it	✅
Set up a new app	Stand up a brand-new application — its own repo, chart, CI/CD with IaC, and database access, across the app + factory + tools repos	✅

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). Until then this folder holds the conventions and the template only.

Rules to contribute

1. Start from _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.