kaizen-agentic/workplans/kaizen-agentic-WP-0007-agent-authoring-doc-generation.md

---
id: KAIZEN-WP-0007
type: workplan
title: "Agent Authoring & Doc Generation (v1.4.0)"
domain: custodian
repo: kaizen-agentic
status: done
owner: kaizen-agentic
topic_slug: custodian
state_hub_workstream_id: a8bc88a4-0ee3-44c6-aff5-9d7f54a316f5
depends_on:
  - KAIZEN-WP-0006
created: "2026-06-18"
updated: "2026-06-18"
tasks:
- id: T01
  state_hub_task_id: debaf0ac-47df-4bbd-aa1f-96c7b96a64ed
  status: done
  title: Fix idempotent CLAUDE.md doc regeneration (installer regex bug)
- id: T02
  state_hub_task_id: e2d9bea8-243b-4b12-bba3-4d43a3bae71c
  status: done
  title: Reusable agent-docs module and kaizen-agentic docs generate command
- id: T03
  state_hub_task_id: 57176887-5344-444c-aa5a-a4aea161ee71
  status: done
  title: Enforce agent frontmatter schema in validate
- id: T04
  state_hub_task_id: 724e3862-602b-4ef0-88b8-ddb78a225046
  status: done
  title: kaizen-agentic create-agent scaffold for new agents
- id: T05
  state_hub_task_id: 4d6e323c-9cad-49ce-9356-9192c20cc986
  status: done
  title: Unit tests for docs generate, schema validation, create-agent
- id: T06
  state_hub_task_id: 6715aa6f-1ee0-4f22-9249-f1cd41763cd1
  status: done
  title: Docs, CLI cheat sheet, CHANGELOG for v1.4.0
---

# KAIZEN-WP-0007 — Agent Authoring & Doc Generation

**Status:** done
**Owner:** kaizen-agentic
**Repo:** kaizen-agentic
**Target version:** 1.4.0
**Depends on:** WP-0006 (scheduled agent execution)

## Goal

Close the WP-0005/WP-0006 deferrals — **agent selection/authoring**, **template
schema enforcement**, and **doc generation** — and fix the doc-generation defect
they exposed. After this workplan, authoring a new agent and keeping project
docs in sync is a first-class, idempotent, validated CLI flow.

## Background

`AgentInstaller._update_documentation()` regenerates the `## Installed Agents`
block in a project's `CLAUDE.md`, but its regex
(`## Installed Agents.*?(?=##|\Z)`) is non-greedy and the `(?=##)` lookahead
matches `### Category` subheadings *inside* the section — so each run leaves the
old category lists and footer in place and appends a fresh copy. The block
duplicates and grows unbounded (reported to state-hub; the corrupting write is
ours). `validate` only checks dependencies and file existence — it does not
enforce the agent frontmatter schema — and there is no scaffolding command for
new agents.

## Tasks

### T01 — Fix idempotent doc regeneration
- Anchor the replace to a top-level heading: `(?=\n## (?!#)|\Z)`.
- Add a regression test that runs regeneration twice and asserts exactly one
  `## Installed Agents`, one footer, one block per category.
- Clean the existing baseline duplication in this repo's `CLAUDE.md`.

### T02 — Reusable agent-docs module + `docs generate`
- Extract the "Installed Agents" rendering into a pure function
  (`render_installed_agents_section`) and an idempotent
  `upsert_installed_agents_section(content, section)`.
- `_update_documentation` reuses them (no behavioral fork).
- New `kaizen-agentic docs generate [--target PATH] [--check]` refreshes the
  section for installed agents; `--check` exits non-zero if it would change
  (CI-friendly).

### T03 — Enforce agent frontmatter schema in `validate`
- Add `validate_frontmatter_schema()` to the registry: required `name`,
  `description`, `category`; `category` ∈ `AgentCategory`; `memory` ∈
  {`enabled`,`disabled`} when present; `model` a non-empty string when present.
- Surface schema errors in `kaizen-agentic validate` alongside dependency
  errors, with actionable messages.

### T04 — `create-agent` scaffold
- `kaizen-agentic create-agent <name> [--category] [--description] [--memory]
  [--target] [--force]` writes a schema-valid `agents/agent-<name>.md` with
  frontmatter + section skeleton.
- Missing `--category`/`--description` fall back to interactive prompts.
- Refuses invalid category; refuses overwrite without `--force`; output passes
  T03 validation.

### T05 — Tests
- `tests/test_agent_docs.py` — idempotency, `docs generate --check`.
- `tests/test_validate_schema.py` — schema pass/fail cases.
- `tests/test_create_agent.py` — scaffold + round-trips through registry.

### T06 — Docs
- `docs/CLI_CHEAT_SHEET.md` — `docs generate`, `create-agent`, schema validate.
- `docs/agency-framework.md` — authoring + doc-sync note.
- `CHANGELOG.md` `[Unreleased]`; `TODO.md` pointer.

## Definition of Done

- Doc regeneration is idempotent (N runs == 1 run); baseline cleaned.
- `kaizen-agentic validate` fails on malformed agent frontmatter with clear errors.
- `kaizen-agentic create-agent` produces an agent that passes `validate`.
- `kaizen-agentic docs generate --check` is green on a synced repo.
- Full test suite + `make release-check` green.

## Out of Scope

- Multi-file agent packages / protocol scaffolding (separate workplan).
- Publishing generated docs to external knowledge bases (info-tech-canon).
- Changing the agent frontmatter schema itself (only enforcing the current one).

## Notes

- Boundary: the doc-regeneration *trigger* (a state-hub routine invoking the
  installer mid-session) is tracked separately in the state-hub inbox; this
  workplan fixes the *write* so the trigger becomes harmless/idempotent.
- `create-agent` writes to `agents/`; remember `make agents-sync-package` before
  release so packaged `data/agents/` parity holds (existing release-check gate).