From 08df3a46979f6d2c66cbcf49be7ad0b8453edee0 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 23:16:36 +0200 Subject: [PATCH] Normalize agent instructions and workplan frontmatter (STATE-WP-0067) - 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 --- .claude/rules/agents.md | 20 ++ .claude/rules/architecture.md | 29 +-- .claude/rules/credential-routing.md | 50 ++++ .claude/rules/first-session.md | 14 +- .claude/rules/repo-boundary.md | 8 +- .claude/rules/repo-identity.md | 10 +- .claude/rules/session-protocol.md | 53 ++++- .claude/rules/stack-and-commands.md | 52 ++--- .claude/rules/workplan-convention.md | 32 ++- AGENTS.md | 219 ++++++++++++++++++ CLAUDE.md | 50 +--- ...en-agentic-WP-0001-community-engagement.md | 2 +- ...kaizen-agentic-WP-0002-agency-framework.md | 2 +- ...kaizen-agentic-WP-0003-measurement-loop.md | 2 +- ...n-agentic-WP-0004-ecosystem-integration.md | 2 +- .../kaizen-agentic-WP-0005-adoption-parity.md | 2 +- ...entic-WP-0006-scheduled-agent-execution.md | 6 +- ...-WP-0007-agent-authoring-doc-generation.md | 5 +- ...P-0008-coulomb-loop-supplier-engagement.md | 2 +- 19 files changed, 409 insertions(+), 151 deletions(-) create mode 100644 .claude/rules/agents.md create mode 100644 .claude/rules/credential-routing.md create mode 100644 AGENTS.md diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md new file mode 100644 index 0000000..0e8a5d9 --- /dev/null +++ b/.claude/rules/agents.md @@ -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. diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index ee84dbd..7c2a645 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -1,29 +1,8 @@ ## Architecture -kaizen-agentic has two distinct layers: + -### 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 diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md new file mode 100644 index 0000000..5b845ba --- /dev/null +++ b/.claude/rules/credential-routing.md @@ -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 "" --json +warden route show --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` diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index a5540c5..d5525d5 100644 --- a/.claude/rules/first-session.md +++ b/.claude/rules/first-session.md @@ -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-.md ← write this first +workplans/KAIZEN-WP-NNNN-.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="", 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} ) ``` diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index 5c190d3..e7f12c3 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -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` + diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index a610ba5..7b1b6ef 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -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 diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index 9cd3dd2..5ab0d4d 100644 --- a/.claude/rules/session-protocol.md +++ b/.claude/rules/session-protocol.md @@ -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//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="") +add_progress_event(summary="...", topic_id="64418556-3206-457a-ba29-6884b5b12cf3", workstream_id="") ``` -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":"","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 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. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index ce5731a..dc53ac6 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -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) + +- **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 diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index ba6ef2c..6c88af2 100644 --- a/.claude/rules/workplan-convention.md +++ b/.claude/rules/workplan-convention.md @@ -1,12 +1,40 @@ ## Workplan Convention (ADR-001) -File location: `workplans/kaizen-agentic-WP-NNNN-.md` -ID prefix: `KAIZEN-WP` +File location: `workplans/KAIZEN-WP-NNNN-.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-.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: "" # 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. + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ed61b21 --- /dev/null +++ b/AGENTS.md @@ -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//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": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -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/" \ + -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 "" --json +warden route show --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` + + + + +--- + +## 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-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-KAIZEN-WP-NNNN-.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: "" # 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: "" # 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/`) diff --git a/CLAUDE.md b/CLAUDE.md index 9131d09..2260c87 100644 --- a/CLAUDE.md +++ b/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 diff --git a/workplans/kaizen-agentic-WP-0001-community-engagement.md b/workplans/kaizen-agentic-WP-0001-community-engagement.md index 56b4c24..414cfb4 100644 --- a/workplans/kaizen-agentic-WP-0001-community-engagement.md +++ b/workplans/kaizen-agentic-WP-0001-community-engagement.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 diff --git a/workplans/kaizen-agentic-WP-0002-agency-framework.md b/workplans/kaizen-agentic-WP-0002-agency-framework.md index f957025..2169880 100644 --- a/workplans/kaizen-agentic-WP-0002-agency-framework.md +++ b/workplans/kaizen-agentic-WP-0002-agency-framework.md @@ -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 diff --git a/workplans/kaizen-agentic-WP-0003-measurement-loop.md b/workplans/kaizen-agentic-WP-0003-measurement-loop.md index 468de6d..97adfb4 100644 --- a/workplans/kaizen-agentic-WP-0003-measurement-loop.md +++ b/workplans/kaizen-agentic-WP-0003-measurement-loop.md @@ -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 diff --git a/workplans/kaizen-agentic-WP-0004-ecosystem-integration.md b/workplans/kaizen-agentic-WP-0004-ecosystem-integration.md index cfd2ebd..9d72f3c 100644 --- a/workplans/kaizen-agentic-WP-0004-ecosystem-integration.md +++ b/workplans/kaizen-agentic-WP-0004-ecosystem-integration.md @@ -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 diff --git a/workplans/kaizen-agentic-WP-0005-adoption-parity.md b/workplans/kaizen-agentic-WP-0005-adoption-parity.md index 1bcea82..fa7b1db 100644 --- a/workplans/kaizen-agentic-WP-0005-adoption-parity.md +++ b/workplans/kaizen-agentic-WP-0005-adoption-parity.md @@ -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 diff --git a/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md b/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md index 4c740b2..254caa2 100644 --- a/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md +++ b/workplans/kaizen-agentic-WP-0006-scheduled-agent-execution.md @@ -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 diff --git a/workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md b/workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md index f71065a..78f4078 100644 --- a/workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md +++ b/workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md @@ -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 diff --git a/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md b/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md index 0795620..1031c32 100644 --- a/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md +++ b/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md @@ -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