coulomb/runbook-tutorials
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
runbook-tutorials/INTENT.md
tegwick 6d3414d8b7 Retire exercise_status: maturity is the only notion; add CLI tests (RBT-WP-0009-T01) 
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: sonnet
Assistant-Process: 295952@bnt-lap001
Assistant-Session: e93f64ad-516c-46eb-9666-aad8d300c477
2026-09-29 21:28:56 +02:00

2.2 KiB
Raw Permalink Blame History

INTENT

Why this repository exists

Operators should be able to carry out real IT administration and operation tasks by following a guided interface instead of a document. Raw runbooks fail in the same ways every time: the operator loses their place, pastes the wrong value, skips a verification, or records nothing. This repository provides the runbook-tutorial engine and user interface that presents a runbook as a sequence of parameterized steps with visible state, gates, copyable commands, verification and rollback, and non-secret evidence of what actually happened.

Direction

  • One engine, many packs. The engine is generic. The runbooks themselves are runbook packs that live in a runbooks/ directory of the repository that owns the procedure. A pack stays next to the system it operates, so its owner can change both together. This repository owns no operational content beyond examples and its own conformance packs.
  • Existing runbooks keep working. The NetKingdom security bootstrap console predates this repository. Its guided flow is carried across through a legacy adapter first and migrated into the pack format only where that pays off.
  • Parameters, not copies. A runbook declares its parameters; the engine renders commands with the operator's values and never asks for secrets.
  • Evidence over assertion. A step is done when its declared check has passed and its outcome is recorded. How far a runbook can be trusted (its maturity) is earned from clean runs in named environments, not declared.
  • Never a secret vault. The engine does not collect, store, log or transmit secret values. It shows the command; the operator runs it.
  • Guide, not executor by default. Steps are run by the operator. Any automated execution is opt-in per step, explicit, and audited.

Relationship to other repositories

  • net-kingdom provides the first runbook pack (security bootstrap) and the operator tutorials, and the console this engine grows out of.
  • Each repo that wants guided operation adds runbooks/<pack>/ and follows the pack specification published here.
  • state-hub records workplans; this repo does not become a task tracker.