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: agents 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).