Normalize agent instructions and workplan frontmatter (STATE-WP-0067)
Some checks failed
ci / test (push) Failing after 44s
Some checks failed
ci / test (push) Failing after 44s
- 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 -->
|
||||
|
||||
Reference in New Issue
Block a user