Normalize agent instructions and workplan frontmatter (STATE-WP-0067)
Some checks are pending
ci / test (push) Waiting to run
Some checks are pending
ci / test (push) Waiting to run
- Align agent files with on-disk workplan prefixes (infer from workplan ids) - Set workplan domain to registered domain_slug; add topic_slug where applicable - Repair frontmatter delimiter formatting; migrate legacy task status literals - Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
This commit is contained in:
20
.claude/rules/agents.md
Normal file
20
.claude/rules/agents.md
Normal file
@@ -0,0 +1,20 @@
|
||||
## 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-management` | 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.
|
||||
@@ -1,29 +1,8 @@
|
||||
## Architecture
|
||||
|
||||
kaizen-agentic has two distinct layers:
|
||||
<!-- TODO: Describe the key design decisions and component structure.
|
||||
Key modules, data flows, external integrations, state machines, etc. -->
|
||||
|
||||
### 1. Python framework (`src/kaizen_agentic/`)
|
||||
## Quick Reference
|
||||
|
||||
- **`core.py`** — `Agent` (abstract base) + `AgentConfig` (dataclass). Tracks performance, supports config updates, implements kaizen interface.
|
||||
- **`optimization.py`** — `OptimizationLoop` (runs improvement cycles, detects trends, generates recommendations) + `PerformanceMetrics` (execution time, success rate, quality scores).
|
||||
- **`metrics.py`** — `MetricsStore` + `OptimizerStore` (project-scoped `.kaizen/metrics/` per ADR-004).
|
||||
|
||||
### 2. Agent definitions (`agents/` — 20 files)
|
||||
|
||||
Markdown instruction sets read and followed by Claude. Not executables. Naming convention: `agent-{name}.md`.
|
||||
Packaged copies live in `src/kaizen_agentic/data/agents/` for `pip install` distribution.
|
||||
|
||||
| Category | Agents |
|
||||
|----------|--------|
|
||||
| Testing | `tdd-workflow`, `test-maintenance`, `testing-efficiency` |
|
||||
| Quality | `code-refactoring`, `datamodel-optimization` |
|
||||
| Process | `requirements-engineering`, `keepaTodofile`, `keepaChangelog`, `keepaContributingfile`, `project-assistant`, `priority-evaluation`, `scope-analyst` |
|
||||
| Infrastructure | `setupRepository`, `tooling-optimization`, `sys-medic` |
|
||||
| Release | `releaseManager` |
|
||||
| Docs | `claude-documentation` |
|
||||
| Support | `wisdom-encouragement` |
|
||||
| Meta | `coach`, `optimization` |
|
||||
|
||||
### Custodian integration
|
||||
|
||||
The state-hub MCP resolves the agents directory via `host_paths[hostname]` → `local_path`. Tools: `list_kaizen_agents(category?)`, `get_kaizen_agent(name)`.
|
||||
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
|
||||
|
||||
50
.claude/rules/credential-routing.md
Normal file
50
.claude/rules/credential-routing.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Credential and access routing
|
||||
|
||||
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
|
||||
for inference. Run this check **before** requesting secrets, API keys, SSH access,
|
||||
login tokens, or database passwords — in any repo, not only `ops-warden`.
|
||||
|
||||
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
|
||||
other credential need belongs to another subsystem. **Do not** message
|
||||
`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
|
||||
|
||||
### Lookup (do this first)
|
||||
|
||||
```bash
|
||||
warden route find "<describe your need>" --json
|
||||
warden route show <catalog-id> --json
|
||||
```
|
||||
|
||||
Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
|
||||
|
||||
| Agent runtime | How to orient |
|
||||
| --- | --- |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=kaizen-agentic` is for coordination, not secret vending |
|
||||
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
|
||||
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
|
||||
|
||||
### Quick routing table
|
||||
|
||||
| I need… | Owner | ops-warden executes? |
|
||||
| --- | --- | --- |
|
||||
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
||||
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
|
||||
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
|
||||
| Authorization decision | flex-auth | No — route only |
|
||||
| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
|
||||
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
|
||||
|
||||
### Anti-patterns (do not do these)
|
||||
|
||||
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
|
||||
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
|
||||
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
||||
|
||||
### Other capabilities (reuse-surface)
|
||||
|
||||
Non-credential capabilities are usually discovered through **reuse-surface** federation
|
||||
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
|
||||
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
||||
get wrong.
|
||||
|
||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||
@@ -1,11 +1,11 @@
|
||||
## First Session Protocol
|
||||
|
||||
Triggered when `get_domain_summary("custodian")` shows **no workstreams**.
|
||||
Triggered when `get_domain_summary("agents")` shows **no workstreams**.
|
||||
The project is registered but work has not yet been structured.
|
||||
|
||||
**Step 1 — Read, don't write**
|
||||
- `~/the-custodian/canon/projects/custodian/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/custodian/roadmap_v0.1.md` — planned phases
|
||||
- `~/the-custodian/canon/projects/agents/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/agents/roadmap_v0.1.md` — planned phases
|
||||
- Scan repo root: README, directory structure, existing code or docs
|
||||
|
||||
**Step 2 — Survey in-progress work**
|
||||
@@ -17,20 +17,20 @@ roadmap phase. **Wait for approval before creating.**
|
||||
|
||||
**Step 4 — Create workplan file first, then DB record (ADR-001)**
|
||||
```
|
||||
workplans/kaizen-agentic-WP-NNNN-<slug>.md ← write this first
|
||||
workplans/KAIZEN-WP-NNNN-<slug>.md ← write this first
|
||||
```
|
||||
Then register in the hub:
|
||||
```
|
||||
create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...")
|
||||
create_workstream(topic_id="64418556-3206-457a-ba29-6884b5b12cf3", title="...", owner="...", description="...")
|
||||
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
|
||||
```
|
||||
|
||||
**Step 5 — Record the setup**
|
||||
```
|
||||
add_progress_event(
|
||||
summary="First session: structured custodian into N workstreams, M tasks",
|
||||
summary="First session: structured agents into N workstreams, M tasks",
|
||||
event_type="milestone",
|
||||
topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
|
||||
topic_id="64418556-3206-457a-ba29-6884b5b12cf3",
|
||||
detail={"workstreams": [...], "tasks_created": M}
|
||||
)
|
||||
```
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This repo owns **kaizen-agentic** only. It does not own:
|
||||
|
||||
- State-hub MCP integration code → `the-custodian/state-hub/mcp_server/server.py`
|
||||
- Agent discovery tools (`list_kaizen_agents`, `get_kaizen_agent`) → `the-custodian`
|
||||
- Custodian coordination and workplan tracking → `the-custodian`
|
||||
- Deployment to custodiancore → `ops-bridge`
|
||||
<!-- TODO: List what belongs in adjacent repos, e.g.:
|
||||
- SSH key management → railiance-infra/
|
||||
- State hub code → state-hub/
|
||||
-->
|
||||
|
||||
@@ -1,9 +1,5 @@
|
||||
## Repo Identity
|
||||
**Purpose:** AI-assisted development quality toolchain. Provides pre-commit hooks, CI/CD pipeline automation, usage telemetry, and CLI improvement scaffolding for the custodian domain.
|
||||
|
||||
**Purpose:** kaizen-agentic — AI agent development framework embracing kaizen (continuous improvement). Provides 17 specialized Claude Code companion agents plus an OptimizationLoop framework for continuous performance measurement and refinement.
|
||||
|
||||
**Domain:** custodian
|
||||
**Domain:** agents
|
||||
**Repo slug:** kaizen-agentic
|
||||
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
|
||||
|
||||
**Custodian integration:** This repo is the single source of truth for all kaizen agents. The state-hub MCP exposes `list_kaizen_agents()` and `get_kaizen_agent(name)` tools so any connected session can discover and load agents without a local copy.
|
||||
**Topic ID:** 64418556-3206-457a-ba29-6884b5b12cf3
|
||||
|
||||
@@ -1,29 +1,50 @@
|
||||
## Session Protocol
|
||||
|
||||
State Hub: http://127.0.0.1:8000
|
||||
Dev Hub (State Hub API): http://127.0.0.1:8000
|
||||
MCP server name in `~/.claude.json`: `dev-hub`
|
||||
|
||||
**Step 1 — Orient**
|
||||
|
||||
Read the offline-safe brief first — it works without a live hub connection:
|
||||
```bash
|
||||
cat .custodian-brief.md
|
||||
```
|
||||
get_domain_summary("custodian")
|
||||
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
|
||||
```
|
||||
If offline: `cd ~/the-custodian/state-hub && make api`
|
||||
get_domain_summary("agents")
|
||||
```
|
||||
If MCP tools are unavailable in the current agent session, use the REST API:
|
||||
```bash
|
||||
curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
|
||||
```
|
||||
If the hub is offline: `cd ~/state-hub && make api`
|
||||
|
||||
**Step 2 — Check inbox**
|
||||
With MCP tools:
|
||||
```
|
||||
get_messages(to_agent="kaizen-agentic", unread_only=True)
|
||||
```
|
||||
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
|
||||
requests before proceeding.
|
||||
|
||||
Without MCP tools:
|
||||
```bash
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=kaizen-agentic&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
**Step 3 — Scan workplans**
|
||||
```bash
|
||||
ls workplans/
|
||||
```
|
||||
For each file with `status: active`, note pending `todo`/`in_progress` tasks.
|
||||
For each file with `status: ready`, `active`, or `blocked`, note pending
|
||||
`wait`/`todo`/`progress` tasks.
|
||||
|
||||
**Step 4 — Present brief**
|
||||
|
||||
1. **Active workstreams** for `custodian` — title, task counts, blocking decisions
|
||||
1. **Active workstreams** for `agents` — title, task counts, blocking decisions
|
||||
2. **Pending tasks** from `workplans/` + any `[repo:kaizen-agentic]` hub tasks
|
||||
3. **Goal guidance** — if `goal_guidance` in summary:
|
||||
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
|
||||
@@ -39,10 +60,26 @@ If no workstreams: follow First Session Protocol (`first-session.md`).
|
||||
> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
|
||||
|
||||
**Session close:**
|
||||
With MCP tools:
|
||||
```
|
||||
add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="<uuid>")
|
||||
add_progress_event(summary="...", topic_id="64418556-3206-457a-ba29-6884b5b12cf3", workstream_id="<uuid>")
|
||||
```
|
||||
If workplan files were modified:
|
||||
Without MCP tools:
|
||||
```bash
|
||||
cd ~/the-custodian/state-hub && make fix-consistency REPO=kaizen-agentic
|
||||
curl -s -X POST http://127.0.0.1:8000/progress/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"topic_id":"64418556-3206-457a-ba29-6884b5b12cf3","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
|
||||
```
|
||||
If workplan files were modified, ensure the local copy is up to date first:
|
||||
```bash
|
||||
git -C <repo_path> pull --ff-only
|
||||
cd ~/state-hub && make fix-consistency REPO=kaizen-agentic
|
||||
```
|
||||
For repos where implementation runs on a remote machine (e.g. CoulombCore),
|
||||
use the combined target which pulls before fixing:
|
||||
```bash
|
||||
cd ~/state-hub && make fix-consistency-remote REPO=kaizen-agentic
|
||||
```
|
||||
**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
|
||||
will sync the file to match DB. **C-16** (repo behind remote) blocks all writes
|
||||
until you pull — intentional to prevent clobbering remote progress.
|
||||
|
||||
@@ -1,43 +1,19 @@
|
||||
## Stack and Commands
|
||||
## Stack
|
||||
|
||||
**Language:** Python 3.8+
|
||||
**Package manager:** uv / pip (`.venv/`)
|
||||
**Test runner:** pytest
|
||||
**Linter/formatter:** flake8 (100-char), black (88-char), mypy (strict)
|
||||
<!-- TODO: Fill in language, frameworks, and key dependencies -->
|
||||
- **Language:**
|
||||
- **Key deps:**
|
||||
|
||||
### Essential commands
|
||||
## Dev Commands
|
||||
|
||||
```bash
|
||||
make setup-complete # First-time setup: venv + package + dev deps
|
||||
source .venv/bin/activate
|
||||
make test # Run full test suite
|
||||
make lint # flake8 linting
|
||||
make format # black formatting
|
||||
make clean # Remove build artifacts
|
||||
# TODO: Fill in the standard commands for this repo
|
||||
|
||||
# Install dependencies
|
||||
|
||||
# Run tests
|
||||
|
||||
# Lint / type check
|
||||
|
||||
# Build / package (if applicable)
|
||||
```
|
||||
|
||||
### TDD workflow
|
||||
|
||||
```bash
|
||||
make tdd-start ISSUE=X # Start issue with requirements validation
|
||||
make tdd-add-test # Add test to current workspace
|
||||
make tdd-status # Show workspace state
|
||||
make tdd-finish # Move tests to main suite
|
||||
```
|
||||
|
||||
### Issue management
|
||||
|
||||
```bash
|
||||
make issue-list # All issues (Gitea)
|
||||
make issue-list-open # Open backlog
|
||||
make issue-show ISSUE=X # Issue detail
|
||||
make issue-create TITLE='...' BODY='...'
|
||||
```
|
||||
|
||||
Run `make help` to see all available targets.
|
||||
|
||||
### Core dependencies (pyproject.toml)
|
||||
|
||||
- `pyyaml>=6.0` — YAML config
|
||||
- `click>=8.0.0` — CLI framework
|
||||
- `pydantic>=2.0.0` — Data validation
|
||||
|
||||
@@ -1,12 +1,40 @@
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
File location: `workplans/kaizen-agentic-WP-NNNN-<slug>.md`
|
||||
ID prefix: `KAIZEN-WP`
|
||||
File location: `workplans/KAIZEN-WP-NNNN-<slug>.md`
|
||||
ID prefix: `KAIZEN-WP-`
|
||||
|
||||
Work items originate as files in this repo **before** being registered in the hub.
|
||||
|
||||
Canonical workplan/workstream frontmatter statuses are:
|
||||
`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
|
||||
Use `proposed` for a newly drafted plan, `ready` after review against current
|
||||
repo state, and `finished` when implementation is complete. `stalled` and
|
||||
`needs_review` are derived health labels, not stored statuses.
|
||||
|
||||
Closed workplans may be moved to `workplans/archived/` with a completion-date
|
||||
prefix: `YYMMDD-KAIZEN-WP-NNNN-<slug>.md`. The frontmatter id remains
|
||||
unchanged; the prefix is only for quick visual reference.
|
||||
|
||||
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
|
||||
`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids
|
||||
`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
|
||||
directly. Promote anything requiring analysis, design, approval, dependencies, or
|
||||
multiple planned phases into a normal workplan.
|
||||
|
||||
Ecosystem todos from other agents arrive as `[repo:kaizen-agentic]` hub tasks —
|
||||
visible at session start. Pick one up by creating the workplan file, then registering
|
||||
the workstream.
|
||||
|
||||
Task blocks use this shape:
|
||||
|
||||
```task
|
||||
id: KAIZEN-WP-NNNN-T01
|
||||
status: wait | todo | progress | done | cancel
|
||||
priority: high | medium | low
|
||||
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
```
|
||||
|
||||
Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
|
||||
blocked work and `cancel` for stopped work.
|
||||
|
||||
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
|
||||
|
||||
219
AGENTS.md
Normal file
219
AGENTS.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# kaizen-agentic — Agent Instructions
|
||||
|
||||
## Repo Identity
|
||||
|
||||
**Purpose:** AI-assisted development quality toolchain. Provides pre-commit hooks, CI/CD pipeline automation, usage telemetry, and CLI improvement scaffolding for the custodian domain.
|
||||
|
||||
**Domain:** agents
|
||||
**Repo slug:** kaizen-agentic
|
||||
**Topic ID:** `64418556-3206-457a-ba29-6884b5b12cf3`
|
||||
**Workplan prefix:** `KAIZEN-WP-`
|
||||
|
||||
---
|
||||
|
||||
## State Hub Integration
|
||||
|
||||
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
|
||||
there is no MCP server for Codex agents.
|
||||
|
||||
| Context | URL |
|
||||
|---------|-----|
|
||||
| Local workstation | `http://127.0.0.1:8000` |
|
||||
| Remote via tunnel | `http://127.0.0.1:18000` |
|
||||
|
||||
### Orient at session start
|
||||
|
||||
```bash
|
||||
# Offline brief — works without hub connection
|
||||
cat .custodian-brief.md
|
||||
|
||||
# Active workstreams for this domain
|
||||
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \
|
||||
| python3 -m json.tool
|
||||
|
||||
# Check inbox
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=kaizen-agentic&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
```
|
||||
|
||||
Mark a message read:
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
### Log progress (required at session close)
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/progress/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"summary": "what was done",
|
||||
"event_type": "note",
|
||||
"author": "codex",
|
||||
"workstream_id": "<uuid>",
|
||||
"task_id": "<uuid>"
|
||||
}'
|
||||
```
|
||||
|
||||
Omit `workstream_id` / `task_id` when not applicable.
|
||||
|
||||
### Update task status
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"status": "progress"}'
|
||||
# values: wait | todo | progress | done | cancel
|
||||
```
|
||||
|
||||
### Flag a task for human review
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"needs_human": true, "intervention_note": "reason"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Protocol
|
||||
|
||||
**Start:**
|
||||
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
|
||||
2. Check inbox: `GET /messages/?to_agent=kaizen-agentic&unread_only=true`; mark read
|
||||
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
|
||||
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
|
||||
|
||||
**During work:**
|
||||
- Update task statuses in workplan files as tasks progress
|
||||
- Record significant decisions via `POST /decisions/`
|
||||
|
||||
**Close:**
|
||||
1. Update workplan file task statuses to reflect progress
|
||||
2. Log: `POST /progress/` with a summary of what changed
|
||||
3. Note for the custodian operator: after workplan file changes, run from
|
||||
`~/state-hub`:
|
||||
```bash
|
||||
make fix-consistency REPO=kaizen-agentic
|
||||
```
|
||||
This syncs task status from files into the hub DB.
|
||||
|
||||
---
|
||||
|
||||
## Credential and access routing
|
||||
|
||||
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
|
||||
for inference. Run this check **before** requesting secrets, API keys, SSH access,
|
||||
login tokens, or database passwords — in any repo, not only `ops-warden`.
|
||||
|
||||
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
|
||||
other credential need belongs to another subsystem. **Do not** message
|
||||
`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
|
||||
|
||||
### Lookup (do this first)
|
||||
|
||||
```bash
|
||||
warden route find "<describe your need>" --json
|
||||
warden route show <catalog-id> --json
|
||||
```
|
||||
|
||||
Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
|
||||
|
||||
| Agent runtime | How to orient |
|
||||
| --- | --- |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=kaizen-agentic` is for coordination, not secret vending |
|
||||
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
|
||||
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
|
||||
|
||||
### Quick routing table
|
||||
|
||||
| I need… | Owner | ops-warden executes? |
|
||||
| --- | --- | --- |
|
||||
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
||||
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
|
||||
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
|
||||
| Authorization decision | flex-auth | No — route only |
|
||||
| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
|
||||
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
|
||||
|
||||
### Anti-patterns (do not do these)
|
||||
|
||||
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
|
||||
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
|
||||
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
||||
|
||||
### Other capabilities (reuse-surface)
|
||||
|
||||
Non-credential capabilities are usually discovered through **reuse-surface** federation
|
||||
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
|
||||
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
||||
get wrong.
|
||||
|
||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||
|
||||
<!-- REPO-AGENTS-EXTENSIONS -->
|
||||
<!-- Append repo-specific agent instructions below this marker.
|
||||
The state-hub template sync preserves content after this line. -->
|
||||
|
||||
---
|
||||
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
Work items originate as files in this repo — not in the hub. The hub is a
|
||||
read/cache/index layer that rebuilds from files.
|
||||
|
||||
**File location:** `workplans/KAIZEN-WP-NNNN-<slug>.md`
|
||||
|
||||
**Archived location:** finished workplans may move to
|
||||
`workplans/archived/YYMMDD-KAIZEN-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
|
||||
the completion/archive date; the frontmatter `id` does not change.
|
||||
|
||||
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
|
||||
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
|
||||
this only for low-risk work completed directly; create a normal workplan for
|
||||
anything needing analysis, design, approval, dependencies, or multiple phases.
|
||||
|
||||
**Frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: KAIZEN-WP-NNNN
|
||||
type: workplan
|
||||
title: "..."
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: proposed | ready | active | blocked | backlog | finished | archived
|
||||
owner: codex
|
||||
topic_slug: ...
|
||||
created: "YYYY-MM-DD"
|
||||
updated: "YYYY-MM-DD"
|
||||
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
---
|
||||
```
|
||||
|
||||
Use `proposed` for a new draft, `ready` after review against current repo
|
||||
state, and `finished` after implementation. `stalled` and `needs_review` are
|
||||
derived health labels, not frontmatter statuses.
|
||||
|
||||
**Task block format** (one per `##` section):
|
||||
|
||||
```
|
||||
## Task Title
|
||||
|
||||
` ` `task
|
||||
id: KAIZEN-WP-NNNN-T01
|
||||
status: wait | todo | progress | done | cancel
|
||||
priority: high | medium | low
|
||||
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
` ` `
|
||||
|
||||
Task description text.
|
||||
```
|
||||
|
||||
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
|
||||
|
||||
To create a new workplan:
|
||||
1. Write the file following the format above
|
||||
2. Notify the custodian operator to run `make fix-consistency REPO=kaizen-agentic`
|
||||
(or send a message to the hub agent via `POST /messages/`)
|
||||
50
CLAUDE.md
50
CLAUDE.md
@@ -1,5 +1,6 @@
|
||||
# kaizen-agentic — Claude Code Instructions
|
||||
|
||||
@SCOPE.md
|
||||
@.claude/rules/repo-identity.md
|
||||
@.claude/rules/session-protocol.md
|
||||
@.claude/rules/first-session.md
|
||||
@@ -7,50 +8,5 @@
|
||||
@.claude/rules/stack-and-commands.md
|
||||
@.claude/rules/architecture.md
|
||||
@.claude/rules/repo-boundary.md
|
||||
|
||||
## Installed Agents
|
||||
|
||||
This project includes the following specialized agents:
|
||||
|
||||
### Documentation
|
||||
|
||||
- **claude-documentation**: Specialized assistant for Claude and Claude Code documentation, features, and best practices
|
||||
- **keepaContributingfile**: Specialized assistant for maintaining CONTRIBUTING.md files following Keep a Contributing-File V0.0.1 format within the Kaizen Agentic framework
|
||||
- **wisdom-encouragement**: Provides encouraging wisdom and guidance for complex implementation tasks and challenging technical work
|
||||
|
||||
### Meta
|
||||
|
||||
- **coach**: Coaching meta-agent that reads all agent memories in a project and synthesises cross-agent briefs and new-agent orientations
|
||||
- **optimization**: Meta-agent that analyzes and optimizes other Claude Code subagents based on their performance data, usage patterns, and effectiveness metrics. Use PROACTIVELY for agent ecosystem improvement.
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **code-refactoring**: Analyze code structure and quality, identify improvement opportunities, and provide actionable refactoring guidance. Use PROACTIVELY for code quality assessment and improvement.
|
||||
- **datamodel-optimization**: Specialized agent that systematically analyzes, optimizes, and enhances dataclasses, models, and data structures within a codebase. Provides comprehensive datamodel improvements including convenience methods, interface consistency, code reduction, and test alignment.
|
||||
|
||||
### Project Management
|
||||
|
||||
- **keepaChangelog**: Specialized assistant for maintaining CHANGELOG.md files following Keep a Changelog format
|
||||
- **keepaTodofile**: Specialized assistant for maintaining TODO.md files following Keep a Todofile V0.0.1 format
|
||||
- **priority-evaluation**: Specialized assistant to help evaluate and establish priorities for issues and tasks.
|
||||
- **project-assistant**: Specialized assistant for project status, progress tracking, and development planning
|
||||
- **releaseManager**: Manages software releases, version control, and publication workflows for Python packages
|
||||
- **scope-analyst**: Analyze a repository and produce/improve SCOPE.md for rapid orientation
|
||||
|
||||
### Development Process
|
||||
|
||||
- **requirements-engineering**: Specialized agent designed to prevent interface compatibility issues and mock object mismatches by ensuring solid foundation planning before implementation. Based on lessons learned from Issue
|
||||
- **tdd-workflow**: Expert guidance for the TDD8 workflow methodology, specializing in the comprehensive ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management and proper test organization.
|
||||
|
||||
### Infrastructure
|
||||
|
||||
- **setupRepository**: Specialized assistant for setting up new Python repositories following PythonVibes best practices
|
||||
- **sys-medic**: Linux/Kubernetes node health assessment agent — diagnoses process, memory, CPU, disk, network, and kubelet issues with safe, prioritized, evidence-driven guidance
|
||||
- **tooling-optimization**: Meta-agent that analyzes and optimizes repository tooling usage to improve development efficiency
|
||||
|
||||
### Testing
|
||||
|
||||
- **test-maintenance**: Specialized agent for analyzing and fixing failing tests in the project
|
||||
- **testing-efficiency**: Specialized agent designed to optimize TDD8 workflow test execution, resolve pytest reliability issues, and enhance overall testing efficiency for red-green iterations. Focuses on smart test selection, parallel execution, and agent integration patterns.
|
||||
|
||||
Use these agents by referencing them in your Claude Code interactions.
|
||||
@.claude/rules/credential-routing.md
|
||||
@.claude/rules/agents.md
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0001
|
||||
type: workplan
|
||||
title: "Community Engagement and Advanced Automation (v1.1.0)"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: completed
|
||||
owner: kaizen-agentic
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0002
|
||||
type: workplan
|
||||
title: "Agency Framework: Project Memory, Coaching, and sys-medic Integration"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: done
|
||||
owner: kaizen-agentic
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0003
|
||||
type: workplan
|
||||
title: "Measurement Loop: Metrics Convention, Collection, and Optimizer Integration"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: completed
|
||||
owner: kaizen-agentic
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0004
|
||||
type: workplan
|
||||
title: "Ecosystem Integration: Helix Forge, activity-core, and artifact-store"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: completed
|
||||
owner: kaizen-agentic
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0005
|
||||
type: workplan
|
||||
title: "Adoption Polish and Fleet Parity (v1.2.0)"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: completed
|
||||
owner: kaizen-agentic
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0006
|
||||
type: workplan
|
||||
title: "Scheduled Agent Execution via activity-core (v1.3.0)"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: done
|
||||
owner: kaizen-agentic
|
||||
@@ -85,8 +85,7 @@ tasks:
|
||||
- id: T18
|
||||
state_hub_task_id: 73986472-bf19-4b13-af1b-6505ab944459
|
||||
status: done
|
||||
title: Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0
|
||||
---
|
||||
title: Update wiki/EcosystemIntegration.md and CHANGELOG for v1.3.0---
|
||||
|
||||
# KAIZEN-WP-0006 — Scheduled Agent Execution via activity-core
|
||||
|
||||
@@ -130,7 +129,6 @@ flowchart LR
|
||||
|
||||
Kaizen-agentic does **not** invoke Claude directly; it **prepares** and **validates**
|
||||
the scheduled run contract.
|
||||
|
||||
---
|
||||
|
||||
## Background
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0007
|
||||
type: workplan
|
||||
title: "Agent Authoring & Doc Generation (v1.4.0)"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: done
|
||||
owner: kaizen-agentic
|
||||
@@ -36,8 +36,7 @@ tasks:
|
||||
- id: T06
|
||||
state_hub_task_id: 6715aa6f-1ee0-4f22-9249-f1cd41763cd1
|
||||
status: done
|
||||
title: Docs, CLI cheat sheet, CHANGELOG for v1.4.0
|
||||
---
|
||||
title: Docs, CLI cheat sheet, CHANGELOG for v1.4.0---
|
||||
|
||||
# KAIZEN-WP-0007 — Agent Authoring & Doc Generation
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
id: KAIZEN-WP-0008
|
||||
type: workplan
|
||||
title: "Coulomb-loop supplier engagement (customer-repo playbook)"
|
||||
domain: custodian
|
||||
domain: agents
|
||||
repo: kaizen-agentic
|
||||
status: done
|
||||
owner: kaizen-agentic
|
||||
|
||||
Reference in New Issue
Block a user