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

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

KAIZEN-WP-0007 — Agent Authoring & Doc Generation

Status: finished 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).