From 0f89e278f054b13de6afbf88538208ee183e1cd1 Mon Sep 17 00:00:00 2001 From: Emanuel Friedrich Date: Wed, 30 Sep 2026 09:07:28 -0300 Subject: [PATCH] README: the other artifact types, when to reach for each, and which ones field use actually wrote; HANDBOOK gains the missing Playbook entry --- HANDBOOK.md | 6 ++++++ README.md | 18 ++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/HANDBOOK.md b/HANDBOOK.md index 11a6cc9..15feb8d 100644 --- a/HANDBOOK.md +++ b/HANDBOOK.md @@ -117,6 +117,12 @@ A task may carry `external_ref` (`jira:PD-123`, `linear:ENG-42`, a URL) when the Statuses: `draft`, `in-review`, `done`. A closed task is `done`, not `implemented` (DR-016). +### Playbook + +Answers: How does an agent carry out a recurring job? + +Use it for procedures an agent repeats and should not reinvent: numbered steps, what to read first, what to produce, where to stop. A playbook tells an agent how to work; it never states product rules, which stay in decisions and specs. Example: KDE-PLAYBOOK-001, drafting knowledge from tickets and wiki pages. + ### Prompt / Agent Context Answers: What context should an AI agent receive? diff --git a/README.md b/README.md index b8f17d5..ae92192 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,24 @@ You don't need to know what an RFC is to use this. There are three kinds of docu In practice this means the agent asks more than you're used to, and every question is one it would otherwise have answered silently in code. +### The other types, for when you need them + +Decisions, RFCs and specs carry almost all the weight. The rest are optional; reach for one when prose in a spec stops being enough. + +| Type | Answers | Reach for it when | +|---|---|---| +| **Product vision** | What are we building, and why? | The domain needs a durable direction that specs can point to. One per domain, edited in place. | +| **User flow** | How does a person move through a capability? | The path has steps and recovery branches worth drawing (Mermaid). | +| **Information architecture** | What information exists, and where does it live? | Screens, sections and hierarchy need to be agreed before building them. | +| **Design system** | What reusable visual rules exist? | Component states and interaction rules apply across features. | +| **Model** | What states, entities and transitions exist? | Several documents depend on the same state machine or entity model. | +| **Contract** | What interface does the code expose? | Clients depend on an API or event. Code under the contract's `implements` paths cannot change without the contract, or the drift gate fails. | +| **Task** | What bounded work remains? | You want work tracked next to the knowledge that justifies it. With Jira or Linear, the tracker owns the task; the file only links it. | +| **Playbook** | How does an agent do a recurring job? | A procedure repeats and should not be reinvented each time, like drafting knowledge from tickets. | +| **Prompt** | What context should an agent receive? | You want the agent's starting context versioned and reviewed like any other rule. | + +For scale: the first production adoption holds 65 decisions, 12 specs and 8 RFCs, plus one vision, model, contract and design-system document each. No tasks, playbooks or prompts. [Every type in full](HANDBOOK.md#artifacts). + ## Quick start Requires Node 22.6+ (only for the tools; your project can be any stack).