[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 |
| [Set up a new tool](new-tool.md) | Add a platform component to the `tools` repo so ArgoCD deploys it | ✅ |
| [Set up a new app](new-app.md) | 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](../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.