jschoubben
3f6d939930
papa-hq has no ledger. Its root is AGENTS.md, CLAUDE.md, README.md, every decision is a numbered record, and its graduation playbook has no path for an unrecorded decision. hal-hq now matches. The ledger's 41 entries classified as: 10 restating a record, 11 restating design docs, 15 describing how this repository works with the reasoning sitting in a README rather than anywhere citable, 3 small rules with no home, 2 superseded stubs. Mostly a copy — and a hand-maintained index, the exact pattern ADR 0022 had just rejected for the decision index on the grounds it drifted after one addition. Keeping one copy of that while removing another is not a position. It also collided by name with 02-DECISIONS/ in any directory listing. Nothing was dropped. Records 0019-0025 give the repository decisions the reasoning they never had: HQ is its own repository and is public, design has two layers, work moves through playbooks, status lives in frontmatter, issues have a front door, the numbering is the flow, HQ is the source of the constitution. 0026 records the ledger's own removal. The three orphan rules went to how-we-build, where a rule is enforced and keeps the incident that earned it — the package rule was genuinely unwritten anywhere. Two lab decisions stated only in the ledger went into the lab design. "Deliberately not decided" went to the research effort and design document each question actually belongs to. The chronological view the ledger provided is now generated from record frontmatter, which is what it was for. The cost, stated in 0026 rather than glossed: a record is more work than a table row, so the risk is a small decision going unrecorded because nobody wanted to write a document. how-we-build takes rules cheaply, which is the mitigation, not a solution.
2.4 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 2026-08-23 | jochen | 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
- 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.
- One long contributing document. Rejected: it is read once, and the step someone needs is never the step they are reading.
- 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/: 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— 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.