Implementation
Adopt the Playbook
A framework produces "interesting article". A working implementation produces "can we adopt this?" This is the implementation.
Most organisations already have the pieces — a coding assistant, CI/CD, static analysis, a ticket system, architecture standards, DORA dashboards, a security policy.
What they generally do not have is a coherent operating model explaining how those pieces work together when humans and agents jointly build software.
This scaffold is that layer, written down as files you can put in a repository. It is a starting point, not a standard to adopt unchanged: copy it, delete what does not apply, and fill in what does.
Download the scaffold
Deliberately tool-agnostic
This is not a Claude Code playbook, a Copilot playbook or a Cursor playbook. Repository-instruction conventions, agent permissions, hooks and skills are converging fast across vendors — and whichever assistant your organisation standardises on will change. The rails should outlive the tooling. Point your assistant's instructions file at the context pack and keep the content in one place.
Structure
What is in the scaffold
engineering-playbook/ |
|
|---|---|
├── README.md |
What this is and the order to adopt it in |
│ |
|
├── context/ |
What contributors must know before starting |
│ ├── AGENTS.md |
Repository instructions for humans and agents |
│ ├── architecture.md |
Boundaries, ownership, irreversible decisions |
│ ├── domain-context.md |
Glossary, critical journeys, non-goals |
│ └── engineering-standards.md |
How we build here, and Definition of Ready |
│ |
|
├── aim/ |
Intent becomes a reviewable contract |
│ ├── feature-spec.md |
The execution contract template |
│ ├── architecture-decision.md |
ADR with reconsideration triggers |
│ └── risk-assessment.md |
Reversibility, blast radius, resulting autonomy level |
│ |
|
├── execute/ |
How much authority a change may carry |
│ ├── autonomy-levels.yaml |
A0–A4 with path mapping |
│ ├── agent-policy.yaml |
Identity, permissions, guardrails, audited bypass |
│ └── hooks/ |
Deterministic enforcement where judgement is not required |
│ |
|
├── verify/ |
What a change must demonstrate |
│ ├── evidence-contract.yaml |
No claim without evidence |
│ ├── quality-gates.yaml |
What blocks, what advises, and where |
│ └── evals/agent-evals.md |
Verify the agent, not only the change |
│ |
|
├── learn/ |
A lesson becomes a durable system change |
│ ├── incident-learning.md |
Routes every incident back into a stage |
│ ├── retrospective.md |
Closes by naming which stage changes |
│ └── context-update.md |
Could this be enforced instead of documented? |
│ |
|
└── metrics/ |
|
└── engineering-scorecard.yaml |
Flow, Quality, AI effectiveness, Economics |
Sequence
Adopt in this order
Adopting all six directories at once usually fails. Adopting context/ alone usually helps.
-
01
Context first
Everything downstream degrades without it. If you do nothing else, do this.
-
02
Autonomy levels next
Decide what may happen without asking. This is the decision that makes delegation safe enough to scale.
-
03
Evidence contract third
Decide what "done" must demonstrate, so completion stops being an assertion.
-
04
Plan and learn as habits settle
Templates only stick once the team feels the cost of not having them.
-
05
Metrics last
Measure once there is something real to measure. Instrumenting chaos produces precise nonsense.
Playbook → Standard → Toolkit → Control plane
The Playbook explains the philosophy. The Toolkit provides the frameworks. This scaffold makes them adoptable. The end state is a control plane: standards that live in templates, pipelines, hooks and platform defaults rather than in documents people are asked to remember.
The further down that stack a rule lives, the less it depends on anyone remembering it.