tegwick
b48a2102d7
Add Helix Forge correlation (HELIX_SESSION_UID env, metrics correlate), artifact-store publish (metrics publish), activity-core ActivityDefinition references, integration patterns docs, and canon/knowledge design artifacts.
312 lines
10 KiB
Markdown
312 lines
10 KiB
Markdown
# 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
|
|
|
|
```markdown
|
|
---
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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):**
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
## 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](../agents/protocols/sys-medic/k3s-node-health-assessment.md) | Structured k3s node health check |
|
|
|
|
See [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md) 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](templates/session-close-protocol.md).
|
|
|
|
### 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](integrations/helix-forge-correlation.md)
|
|
and [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md).
|
|
|
|
### Evidence retention
|
|
|
|
After `metrics optimize`, optionally publish optimizer outputs to **artifact-store**:
|
|
|
|
```bash
|
|
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](integrations/optimizer-artifact-manifest.md).
|
|
|
|
---
|
|
|
|
## Related Documents
|
|
|
|
- [ADR-001: Workplan Convention](adr/ADR-001-workplan-convention.md)
|
|
- [ADR-002: Project Memory Convention](adr/ADR-002-project-memory-convention.md)
|
|
- [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md)
|
|
- [ADR-004: Project Metrics Convention](adr/ADR-004-project-metrics-convention.md)
|
|
- [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md) — two-layer measurement model
|
|
- [WP-0002: Agency Framework](../workplans/kaizen-agentic-WP-0002-agency-framework.md)
|
|
- [WP-0003: Measurement Loop](../workplans/kaizen-agentic-WP-0003-measurement-loop.md)
|
|
- [WP-0004: Ecosystem Integration](../workplans/kaizen-agentic-WP-0004-ecosystem-integration.md)
|