## Purpose  ## Scope  ## Prerequisites  ## Procedure ### Step 1 — <name>  ### Step 2 — <name> ... ## Interpretation  ## Remediation  ## Notes  ``` ### Lifecycle - Protocols are **created** when a repeatable procedure is identified during agent work - Protocols are **refined** across sessions as the owning agent accumulates experience - Protocols are **referenced** by agent prompts using the convention: *"If available, use the `<slug>` protocol at `agents/protocols/<agent-name>/<slug>.md`"* - Protocols are **human-readable** and can be executed without an AI agent present ### Relationship to agent memory Agent memory captures *what was learned* in a project. Protocols capture *how to do a repeatable thing* independent of any specific project. A protocol may be updated based on findings across many projects, but it does not store project-specific state. ### CLI interface ``` kaizen-agentic protocols list [agent] # List protocols (optionally filtered by agent) kaizen-agentic protocols show <agent> <slug> # Print a protocol ``` `kaizen-agentic memory init sys-medic` will scaffold the sys-medic protocol directory alongside the memory file when protocols exist for that agent. ### README Each `agents/protocols/` directory contains a `README.md` explaining the convention and listing available protocols. ## Consequences - Protocols are independently versioned and evolvable without touching agent prompts. - The `agents/protocols/` directory is part of the kaizen-agentic repo and distributed alongside agent definitions. - Operators can view, adapt, or execute protocols without running the CLI. - The first protocol — sys-medic's k3s node health assessment — migrates from its current location into `agents/protocols/sys-medic/k3s-node-health-assessment.md`.

--- id: ADR-003 title: Protocols Artifact Convention status: accepted date: "2026-03-18" --- # ADR-003 — Protocols Artifact Convention ## Status Accepted ## Context Some agents perform structured, repeatable assessments or remediation procedures (e.g. sys-medic's k3s node health assessment). These procedures exist as narrative text embedded in agent prompts or companion documents, making them hard to discover, reference, version, or evolve independently of the agent prompt. Protocols are distinct from agent prompts: - Agent prompts shape AI behaviour - Protocols are procedural checklists for humans and agents to execute They need their own artifact type with a stable location and structure. ## Decision ### File location ``` agents/protocols//.md ``` Protocols live inside the `agents/` directory alongside agent definitions, grouped by owning agent. The `agents/protocols/` subtree is a managed artifact collection — not executable code, not agent prompts. ### File structure ```markdown --- agent: slug: title: version: last_updated: --- # ## Purpose  ## Scope  ## Prerequisites  ## Procedure ### Step 1 — <name>  ### Step 2 — <name> ... ## Interpretation  ## Remediation  ## Notes  ``` ### Lifecycle - Protocols are **created** when a repeatable procedure is identified during agent work - Protocols are **refined** across sessions as the owning agent accumulates experience - Protocols are **referenced** by agent prompts using the convention: *"If available, use the `<slug>` protocol at `agents/protocols/<agent-name>/<slug>.md`"* - Protocols are **human-readable** and can be executed without an AI agent present ### Relationship to agent memory Agent memory captures *what was learned* in a project. Protocols capture *how to do a repeatable thing* independent of any specific project. A protocol may be updated based on findings across many projects, but it does not store project-specific state. ### CLI interface ``` kaizen-agentic protocols list [agent] # List protocols (optionally filtered by agent) kaizen-agentic protocols show <agent> <slug> # Print a protocol ``` `kaizen-agentic memory init sys-medic` will scaffold the sys-medic protocol directory alongside the memory file when protocols exist for that agent. ### README Each `agents/protocols/` directory contains a `README.md` explaining the convention and listing available protocols. ## Consequences - Protocols are independently versioned and evolvable without touching agent prompts. - The `agents/protocols/` directory is part of the kaizen-agentic repo and distributed alongside agent definitions. - Operators can view, adapt, or execute protocols without running the CLI. - The first protocol — sys-medic's k3s node health assessment — migrates from its current location into `agents/protocols/sys-medic/k3s-node-health-assessment.md`.