Bernd Worsch
53dfd55916
- ADR-003: protocols artifact convention (location, structure, lifecycle) - agents/protocols/README.md: directory-level index and usage guide - agents/protocols/sys-medic/k3s-node-health-assessment.md: full structured k3s node health assessment protocol (8 steps: OS baseline, process hygiene, memory, CPU, disk, network, k3s node state, runtime services) - agent-sys-medic.md: add memory: enabled frontmatter, session-start/close protocols, node-profile memory template extensions, protocol reference in Default Task - cli.py: add protocols command group (list, show); extend memory init to hint protocol commands for agents that have protocols Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.3 KiB
id, title, status, date
| id | title | status | date |
|---|---|---|---|
| ADR-003 | Protocols Artifact Convention | accepted | 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/<agent-name>/<slug>.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
---
agent: <agent-name>
slug: <slug>
title: <human-readable title>
version: <semver>
last_updated: <ISO date>
---
# <Title>
## Purpose
<!-- One paragraph: what this protocol checks or achieves -->
## Scope
<!-- What systems, components, or conditions this protocol applies to -->
## Prerequisites
<!-- What must be true before starting -->
## Procedure
### Step 1 — <name>
<!-- Commands, checks, observations -->
### Step 2 — <name>
...
## Interpretation
<!-- How to read the results: what is normal, what is a warning, what requires action -->
## Remediation
<!-- Common issues and how to resolve them -->
## Notes
<!-- Version history, known limitations, related protocols -->
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 atagents/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.