kaizen-agentic/docs/agency-framework.md

Agency Framework

kaizen-agentic is not just a library of agent instruction sets — it is an agency: a system where agents are deployed into projects with their own persistent memory, learn from experience, and are guided by a coaching meta-agent that distils patterns across the entire fleet.

Overview

When you deploy a kaizen-agentic agent into a project, it can accumulate project-scoped memory — a structured file written at session close and read at session start. A Coach meta-agent reads across all agent memories and produces orientation briefs for newly deployed agents: what has been tried, what worked, what to watch out for.

Agents arrive in a project informed, not blank.

---

Project Memory

Location Convention

<project-root>/.kaizen/agents/<agent-name>/memory.md

The .kaizen/ directory is analogous to .claude/ — a project-level configuration and state directory owned by the kaizen-agentic ecosystem.

Memory File Structure

---
agent: <name>
project: <project-root or slug>
last_updated: <ISO date>
session_count: <n>
---

## Project Context
<!-- What this agent knows about the project it is working in -->

## Accumulated Findings
<!-- Patterns, recurring issues, key decisions the agent has encountered -->

## What Worked
<!-- Approaches that produced good results in this project -->

## Watch Points
<!-- Recurring risks, traps, or areas requiring extra care -->

## Open Threads
<!-- Things noticed but not yet acted on -->

## Session Log
<!-- One-line entry per session: date · summary · outcome -->

Session Protocols

Session-start (all agents with memory: enabled):

1. Check for .kaizen/agents/<name>/memory.md in the project root.
2. If present, read it before beginning work.
3. Acknowledge the memory in the opening brief.

Session-close (all agents with memory: enabled):

1. Update ## Accumulated Findings, ## What Worked, ## Watch Points as appropriate.
2. Append one line to ## Session Log: YYYY-MM-DD · <summary> · <outcome>.
3. Bump last_updated and session_count.

---

Agent YAML Frontmatter

Each agent definition (agents/agent-<name>.md) includes a YAML frontmatter block:

---
name: <name>
description: <one-line description>
category: <category>
memory: enabled   # or: disabled
---

The memory field defaults to enabled. Set memory: disabled for agents that are stateless by design (e.g. wisdom-encouragement).

---

The Coach Meta-Agent

agents/agent-coach.md is a meta-agent — it performs no domain work (coding, testing, infrastructure). Its sole purpose is synthesis and advice.

What the Coach Does

• Cross-agent synthesis: reads all .kaizen/agents/*/memory.md files, identifies shared patterns, cross-domain risks, and contradictions
• New-agent orientation: when briefing a specific agent, filters all existing memories for what is relevant and produces a targeted brief
• Fleet health overview: summarises which agents are active, stale, or missing; flags high-session-count agents with open threads

Invoking the Coach

Via CLI (assembles raw memory context):

kaizen-agentic memory brief <agent-name>

This prints a structured orientation brief. Pass the output to a Claude session with agents/agent-coach.md loaded for full LLM synthesis.

Directly in a Claude session:

Coach, brief the sys-medic agent on this project.
Coach, what patterns have you observed across all agents?

The Coach maintains its own memory at .kaizen/agents/coach/memory.md covering fleet-level observations over time.

---

CLI Reference

The memory command group manages project-scoped agent memory:

kaizen-agentic memory show <agent>      # Print agent memory for the current project
kaizen-agentic memory init <agent>      # Scaffold an empty memory file
kaizen-agentic memory brief <agent>     # Assemble orientation context for the coach
kaizen-agentic memory clear <agent>     # Wipe memory (with confirmation prompt)

Options

memory brief accepts:

• --target / -t — project root (default: current directory)
• --raw — dump raw memory file contents without the structured header

Example Workflow

# First deployment of sys-medic into a project
kaizen-agentic memory init sys-medic

# After a few sessions, brief an incoming tdd-workflow agent
kaizen-agentic memory brief tdd-workflow
# → paste output into Claude with agent-coach.md loaded

# Review accumulated memory for a specific agent
kaizen-agentic memory show project-management

---

Protocol Runbooks

Agents can reference protocol runbooks — structured, human-readable procedural checklists for structured assessments or remediation work. Protocols are distinct from agent prompts:

• Agent prompts (agents/agent-*.md) shape AI behaviour
• Protocols (agents/protocols/<agent>/<slug>.md) are procedural documents for humans and agents to execute

Location Convention

agents/protocols/
  <agent-name>/
    <slug>.md    ← one file per protocol

Protocol Frontmatter

Each protocol file has a YAML frontmatter block:

---
agent: <agent-name>
slug: <slug>
title: <human-readable title>
version: 1.0.0
last_updated: "<ISO date>"
---

Referencing Protocols from Agents

Agents with memory: enabled check for relevant protocols at session start and reference them in their session-start protocol block. For example, sys-medic's session-start protocol instructs:

"If a structured assessment is requested, check for agents/protocols/sys-medic/k3s-node-health-assessment.md and use it as your procedure."

CLI Reference

kaizen-agentic protocols list                        # List all protocols
kaizen-agentic protocols list sys-medic              # Filter by agent
kaizen-agentic protocols show sys-medic k3s-node-health-assessment

sys-medic Memory and Protocols Integration

sys-medic extends the base memory template with three additional sections for operational continuity across sessions:

## Node Profiles
<!-- Per-node operational baseline established over sessions -->
<!-- hostname | typical load | known quirks | last assessment date -->

## Recurring Findings
<!-- Issues seen more than once: pattern · first seen · frequency -->

## Cleared Issues
<!-- Issues that were resolved: what was done · when · outcome -->

These sections are maintained automatically by the sys-medic session-close protocol.

The k3s Node Health Assessment (agents/protocols/sys-medic/k3s-node-health-assessment.md) is the first protocol runbook — a step-by-step procedure covering OS baseline, process hygiene, memory, CPU, disk, network, Kubernetes node state, and k3s runtime health.

Available Protocols

Agent	Protocol	Description
sys-medic	k3s-node-health-assessment	Structured k3s node health check

See ADR-003: Protocols Artifact Convention for the full specification.

---

Agents with Memory Enabled

All agents that do session-bound project work have memory: enabled in their frontmatter and include session-start/session-close protocol blocks:

Agent	Category	Notes
project-management	process	Reference implementation of the session protocol pattern
tdd-workflow	testing
requirements-engineering	process
scope-analyst	process
sys-medic	infrastructure	Extended memory template (node profiles, recurring findings)
coach	meta	Fleet-level memory

---

Project Metrics

Project-scoped quantitative metrics complement qualitative memory (ADR-002). Per-execution records live under .kaizen/metrics/<agent>/ and feed the kaizen optimizer loop.

Location

<project-root>/.kaizen/metrics/<agent-name>/
  executions.jsonl
  summary.json

<project-root>/.kaizen/metrics/optimizer/
  analysis.json
  recommendations.jsonl

CLI (WP-0003)

kaizen-agentic metrics record <agent>   # Append execution record at session close
kaizen-agentic metrics show <agent>     # Summary + recent executions
kaizen-agentic metrics list             # Agents with metrics in project
kaizen-agentic metrics export <agent>   # Dump executions.jsonl
kaizen-agentic metrics optimize [agent] # Run optimizer on project metrics (≥10 records)
kaizen-agentic metrics correlate <uid>  # Helix Forge digest lookup (read-only)
kaizen-agentic metrics publish          # Register optimizer output in artifact-store

memory brief includes a ## Performance Summary when metrics exist (success rate, avg quality, execution time, trend arrows).

memory init scaffolds .kaizen/metrics/<agent>/ by default (--no-metrics to skip). Record outcomes at session close per session-close protocol template.

Fleet correlation

Project metrics correlate with Helix Forge fleet session metrics in agentic-resources via optional helix_session_uid (ADR-004).

• HELIX_SESSION_UID (and related env vars) auto-merge on metrics record
• metrics correlate <uid> looks up fleet digest when HELIX_STORE_DB is set

See integrations/helix-forge-correlation.md and wiki/EcosystemIntegration.md.

Evidence retention

After metrics optimize, optionally publish optimizer outputs to artifact-store:

export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<write-token>
kaizen-agentic metrics publish --target .

Package uses retention_class: raw-evidence (180d). Local .kaizen/metrics/optimizer/ remains authoritative when publish is skipped.

Manifest: integrations/optimizer-artifact-manifest.md.

---

Related Documents

• ADR-001: Workplan Convention
• ADR-002: Project Memory Convention
• ADR-003: Protocols Artifact Convention
• ADR-004: Project Metrics Convention
• wiki/EcosystemIntegration.md — two-layer measurement model
• WP-0002: Agency Framework
• WP-0003: Measurement Loop
• WP-0004: Ecosystem Integration