---
id: CUST-WP-0016
type: workplan
title: Kaizen-Agentic Integration — Agents for Custodian & Registered Repos
domain: custodian
repo: the-custodian
status: done
state_hub_workstream_id: bd50b948-6013-4953-b622-6bf4b163e7c5
created: 2026-03-17
updated: 2026-03-17
---

# CUST-WP-0016 — Kaizen-Agentic Integration

## Problem

The custodian system has 17 specialized kaizen agents available in
`~/kaizen-agentic/agents/` but no formal integration path. Worker agents in
registered repos cannot discover or invoke them. The custodian hub agent has
no direct access either. The agents represent valuable reusable expertise
(TDD workflow, code refactoring, test maintenance, requirements engineering,
etc.) that should be available across the entire system.

## Goal

Make kaizen agents available to:
1. The hub Claude session (`the-custodian`) — via direct install into `agents/`
2. Worker agents in any registered repo — via MCP tools (`list_kaizen_agents`,
   `get_kaizen_agent`) that resolve the kaizen-agentic path using `host_paths`
3. Newly registered repos — via a new `agents.md` rule template added to the
   `.claude/rules/` standard structure

## Design

```
kaizen-agentic repo  (single source of truth, registered with state-hub)
       │
       │  host_paths[hostname] → path resolution (same as consistency_check.py)
       ▼
state-hub MCP server
  list_kaizen_agents(category?)   → [{name, description, category}]
  get_kaizen_agent(name)          → full agent markdown content
       │
       │  any session connected to the hub MCP
       ▼
Worker in any registered repo
  "act as the tdd-workflow agent"
  → calls get_kaizen_agent("tdd-workflow")
  → follows returned instructions

the-custodian/agents/  (curated direct install — no MCP round-trip for hub)
  agent-tdd-workflow.md
  agent-code-refactoring.md
  agent-test-maintenance.md
  agent-requirements-engineering.md
  agent-keepaTodofile.md
  agent-project-assistant.md
```

## Scope

**In scope:**
- Register kaizen-agentic repo with state-hub (host_paths on both machines)
- MCP tools: `list_kaizen_agents`, `get_kaizen_agent`
- `agents.md` rule template + add to `claude-md.template`
- Direct install of 6 curated agents into `the-custodian/agents/`
- TOOLS.md update

**Out of scope (later workplan):**
- OptimizationLoop integration
- Per-repo agent customisation via kaizen extensions
- Automated agent update propagation

---

## Task: Register kaizen-agentic with state-hub

```task
id: CUST-WP-0016-T01
status: done
priority: high
state_hub_task_id: "5edbf08b-fa4b-4968-aeb1-3a943ff00dc3"
```

- Run `make register-project DOMAIN=custodian PROJECT_PATH=/home/worsch/kaizen-agentic`
- Verify `host_paths[worsch-hostname]` is set
- Migrate kaizen-agentic's CLAUDE.md to `.claude/rules/` structure (ops-bridge pattern)
- Register host path on custodiancore once tunnel is up:
  `make register-path REPO=kaizen-agentic PATH=/home/tegwick/kaizen-agentic`
  (if kaizen-agentic is present on custodiancore; skip if not)

---

## Task: MCP tools — list_kaizen_agents + get_kaizen_agent

```task
id: CUST-WP-0016-T02
status: done
priority: high
state_hub_task_id: "8850c0de-2c15-4ab2-bcb6-e787596403dd"
```

Add to `state-hub/mcp_server/server.py`:

```python
list_kaizen_agents(category: str | None = None) -> str
```
- Resolves kaizen-agentic repo path via `host_paths[hostname]` → `local_path` fallback
- Reads YAML frontmatter from `agents/agent-*.md`
- Returns JSON list of `{name, description, category, dependencies}`
- Optional `category` filter

```python
get_kaizen_agent(name: str) -> str
```
- Resolves path same as above
- Returns full markdown content of `agents/agent-{name}.md`
- 404-style error if agent not found

Both tools share a helper `_kaizen_agents_dir(api_base) -> Path` that calls
`GET /repos/kaizen-agentic/` and applies the same `resolve_repo_path()` logic.

Update `mcp_server/TOOLS.md` with the new tools under a new **Kaizen Agents** section.

---

## Task: agents.md rule template

```task
id: CUST-WP-0016-T03
status: done
priority: high
state_hub_task_id: "29c67b37-186d-4dea-b664-f6177dbd937c"
```

Create `state-hub/scripts/project_rules/agents.template`:

```markdown
## Kaizen Agents

Specialized agent personas available on demand via the state-hub MCP.

**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them

Common agents:
| Agent | Category | When to use |
|-------|----------|-------------|
| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
| `code-refactoring` | quality | Code quality analysis and safe refactoring |
| `test-maintenance` | testing | Diagnose and fix failing tests |
| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
| `keepaTodofile` | process | Maintain TODO.md during work |
| `project-assistant` | process | Track status, determine next steps |
| `datamodel-optimization` | quality | Optimize dataclasses and data structures |

All 17 agents: call `list_kaizen_agents()` for the full list.
```

Add `@.claude/rules/agents.md` to `scripts/project_rules/claude-md.template`.

---

## Task: Direct install into the-custodian

```task
id: CUST-WP-0016-T04
status: done
priority: medium
state_hub_task_id: "78b2b375-9566-4699-9c85-0a67a80509b3"
```

Install curated kaizen agents directly into `the-custodian/agents/`:

```bash
cd /home/worsch/the-custodian
kaizen-agentic install \
  tdd-workflow \
  code-refactoring \
  test-maintenance \
  requirements-engineering \
  keepaTodofile \
  project-assistant \
  --target .
```

Commit the resulting `agents/` directory.

---

## Task: TOOLS.md + global CLAUDE.md update

```task
id: CUST-WP-0016-T05
status: done
priority: medium
state_hub_task_id: "0aed1674-b69e-4f97-98db-78c7ef2af75c"
```

- Add **Kaizen Agents** section to `mcp_server/TOOLS.md`
- Update `~/.claude/CLAUDE.md` session protocol to mention kaizen agent
  availability (one line: "Call `list_kaizen_agents()` to discover available
  specialized agent personas")

---

## Milestones

| # | Milestone | Tasks |
|---|-----------|-------|
| M1 | kaizen-agentic tracked in state-hub | T01 |
| M2 | Agents accessible via MCP from any connected session | T02 |
| M3 | New repos get agents.md rule automatically | T03 |
| M4 | Hub Claude has direct agent access | T04 |
| M5 | Documentation complete | T05 |

## Dependencies

- host_paths feature (CUST-WP host-paths, merged 2026-03-16) — live ✓
- ops-bridge @-import CLAUDE.md pattern (2026-03-17) — live ✓