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:
116
docs/adr/ADR-003-protocols-artifact-convention.md
Normal file
116
docs/adr/ADR-003-protocols-artifact-convention.md
Normal 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`.
|
||||
Reference in New Issue
Block a user