Gabriel Radureau
2d76eb45c1
Two agent-oriented runbooks under vibe/runbooks/ with [AGENT]/[HUMAN] step markers, grounded in real diffs: - new-tool.md : add a platform component to the tools repo so ArgoCD deploys it into the tools namespace (wrapper Chart.yaml + the tool library + a row in chart/values.yaml; optional iac/ for secrets). Mirrors the prometheus/crowdsec additions. - new-app.md : stand up a brand-new application across THREE repos (app + factory + tools) with the strict ordering dependency and the TERRAFORM_SSH_KEY pitfall. Phase-by-phase mapped to the dance-lessons-coach onboarding PRs (#89/#97/#98/#99/#100), factory #1/#2, tools #1; the FR doc/runbooks/new-web-app is linked as the detailed companion. 2 mermaid diagrams MCP-validated; zero dead links across the vibe tree. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
63 lines
4.2 KiB
Markdown
63 lines
4.2 KiB
Markdown
[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.
|