---
status: accepted
date: 2026-08-23
deciders: jochen
reconstructed: false
---

# 21. Every workflow is a playbook, and agents operate through them

## Context

HQ stated a knowledge flow — research becomes design — and nowhere stated how anything moves
along it. What graduation required, who wrote the decision, what closed an effort, what
happened when something shipped: all of it was convention held in one person's head.

A large share of the work here is done by agents. An unwritten convention is not available to
an agent at all, so each one either invents a procedure or asks. Both produce a repository
whose shape depends on who last touched it.

## Considered options

1. **Convention, learned by reading existing documents.** Rejected — the status quo. It
   transmits shape but not rules, and it transmits the mistakes along with the pattern.
2. **One long contributing document.** Rejected: it is read once, and the step someone needs
   is never the step they are reading.
3. **A playbook per workflow, each with trigger, steps and outputs, wrapped by a thin skill.**
   Chosen.

## Decision

Every workflow is a playbook in [`00-META/process/`](../00-META/process/): trigger, who runs
it, steps, outputs. Engineers and agents follow the same playbooks, and **agents must not act
outside them**.

Each playbook is wrapped by a thin skill that defers to it as authoritative and adds only
mechanical scaffolding — next free number, frontmatter block, where the file goes. The
playbook holds the reasoning; the skill holds the steps. When they disagree, the playbook
wins.

## Consequences

- An agent arriving with no context can act correctly, because the procedure is retrievable
  rather than remembered.
- The playbooks are themselves reviewable. A bad rule can be found and changed, which is not
  true of a convention.
- Duplication between playbook and skill is real, and is managed by making the skill thin and
  naming the playbook as authoritative in the skill's first lines. Nothing prevents them
  drifting; the constraint is that only one carries reasoning.
- A workflow with no playbook is a workflow agents will get wrong. Adding one is part of
  adding the workflow.

## References

- [`00-META/process/00-overview.md`](../00-META/process/00-overview.md) — the five playbooks
  and the flow they implement.
- Modelled on the process layer in the sibling HQ repository for the PAPA platform, which
  arrived at the same shape and the same thin-skill split.