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>
117 lines
3.3 KiB
Markdown
117 lines
3.3 KiB
Markdown
---
|
|
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/<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
|
|
|
|
```markdown
|
|
---
|
|
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 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`.
|