feat(protocols): add protocols artifact convention, sys-medic protocol + CLI (WP-0002 T17-T24)

- 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>
This commit is contained in:
2026-03-18 23:48:09 +00:00
parent 15f4cce238
commit 53dfd55916
5 changed files with 593 additions and 0 deletions

View File

@@ -0,0 +1,116 @@
---
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`.