221 lines
6.5 KiB
Markdown
221 lines
6.5 KiB
Markdown
---
|
|
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 ✓
|