feat: agent authoring & doc generation (WP-0007, v1.4.0)

New authoring tooling and a fix for the doc-regeneration defect it exposed.

Added:
- src/kaizen_agentic/agent_docs.py — render + idempotent upsert of the
  CLAUDE.md "## Installed Agents" section (shared by installer and CLI)
- `kaizen-agentic docs generate [--check]` — idempotent doc refresh / CI gate
- `kaizen-agentic create-agent` — scaffold a schema-valid agent
- Frontmatter schema validation in `kaizen-agentic validate`
  (required name/description/category, known category, valid memory/model)
- tests: test_agent_docs, test_validate_schema, test_create_agent

Fixed:
- _update_documentation regex duplicated the Installed Agents block on every
  run (stopped at the first ### subheading) — now idempotent
- declared frontmatter `category` is authoritative (heuristic is fallback)
- list_installed_agents reads the frontmatter name, not the filename
- renamed agent-project-management.md -> agent-project-assistant.md to satisfy
  the agent-<name>.md convention (eliminates a name/filename collision that
  caused install/update to write a divergent duplicate)
- test_cli_error_handling no longer installs into the repo root (uses tmp)

Version 1.4.0; CHANGELOG, CLI cheat sheet, agency-framework, TODO updated.
Workplan KAIZEN-WP-0007 closed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/kaizen_agentic/cli.py

@@ -25,6 +25,10 @@ from .schedule import (
     schedule_path,
     validate_schedule,
 )
+from .agent_docs import (
+    render_installed_agents_section,
+    upsert_installed_agents_section,
+)
 
 
 def safe_cli_wrapper():
@@ -418,8 +422,21 @@ def validate(target: str):
 
     target_path = Path(target).resolve()
 
+    # Validate agent frontmatter schema
+    click.echo("Validating agent frontmatter schema...")
+    schema_errors = registry.validate_frontmatter_schema()
+
+    if schema_errors:
+        click.echo("Frontmatter schema errors:")
+        for agent_file, errors in schema_errors.items():
+            click.echo(f"  {agent_file}:")
+            for error in errors:
+                click.echo(f"    ❌ {error}")
+    else:
+        click.echo("  ✅ Frontmatter schema validation passed")
+
     # Validate registry agents
-    click.echo("Validating agent registry...")
+    click.echo("\nValidating agent registry...")
     registry_errors = registry.validate_agents()
 
     if registry_errors:
@@ -1565,6 +1582,156 @@ def _render_prepare_markdown(bundle: dict) -> str:
     return "\n".join(lines)
 
 
+@cli.command("create-agent")
+@click.argument("name")
+@click.option(
+    "--category",
+    "-c",
+    type=click.Choice([c.value for c in AgentCategory]),
+    help="Agent category (prompted if omitted)",
+)
+@click.option("--description", "-d", help="One-line description (prompted if omitted)")
+@click.option(
+    "--memory",
+    type=click.Choice(["enabled", "disabled"]),
+    default="enabled",
+    show_default=True,
+    help="Project memory support",
+)
+@click.option("--model", help="Optional model hint (e.g. claude-opus-4-8)")
+@click.option(
+    "--target",
+    "-t",
+    default=".",
+    help="Project root containing agents/ (default: current)",
+)
+@click.option("--force", is_flag=True, help="Overwrite an existing agent file")
+def create_agent(
+    name: str,
+    category: Optional[str],
+    description: Optional[str],
+    memory: str,
+    model: Optional[str],
+    target: str,
+    force: bool,
+):
+    """Scaffold a new schema-valid agent definition (agents/agent-<name>.md)."""
+    if not category:
+        category = click.prompt(
+            "Category", type=click.Choice([c.value for c in AgentCategory])
+        )
+    if not description:
+        description = click.prompt("One-line description")
+
+    agents_dir = _project_root(target) / "agents"
+    agents_dir.mkdir(parents=True, exist_ok=True)
+    agent_path = agents_dir / f"agent-{name}.md"
+
+    if agent_path.exists() and not force:
+        click.echo(f"Agent already exists: {agent_path}")
+        click.echo("  Use --force to overwrite.")
+        sys.exit(1)
+
+    frontmatter = [
+        "---",
+        f"name: {name}",
+        f"description: {description}",
+        f"category: {category}",
+        f"memory: {memory}",
+    ]
+    if model:
+        frontmatter.append(f"model: {model}")
+    frontmatter.append("---")
+
+    title = name.replace("-", " ").title()
+    body = f"""
+# {title} Agent
+
+## Role
+
+<!-- One paragraph: what this agent does and what it does not do. -->
+
+## When to Use
+
+<!-- Triggers and situations where this agent should be invoked. -->
+
+## Instructions
+
+<!-- Step-by-step guidance the agent follows. -->
+
+## Output
+
+<!-- What the agent produces and in what format. -->
+"""
+    agent_path.write_text("\n".join(frontmatter) + "\n" + body)
+
+    # Validate the scaffold passes the frontmatter schema (T03).
+    errors = (
+        AgentRegistry(agents_dir).validate_frontmatter_schema().get(agent_path.name, [])
+    )
+    if errors:
+        click.echo(f"⚠️  Created {agent_path} but it has schema issues:")
+        for error in errors:
+            click.echo(f"    ❌ {error}")
+        sys.exit(1)
+
+    click.echo(f"✅ Created agent: {agent_path}")
+    click.echo("  Edit the skeleton, then validate: kaizen-agentic validate")
+    click.echo("  Before release: make agents-sync-package")
+
+
+@cli.group()
+def docs():
+    """Generate project documentation from agent metadata."""
+    pass
+
+
+@docs.command("generate")
+@click.option("--target", "-t", default=".", help="Project root (default: current)")
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Exit non-zero if CLAUDE.md would change (do not write)",
+)
+def docs_generate(target: str, check: bool):
+    """Refresh the '## Installed Agents' section of CLAUDE.md (idempotent)."""
+    target_path = _project_root(target)
+    # Resolve agents from the target project's own agents/ when present, so
+    # `docs generate --target other/project` documents that project's agents
+    # rather than the registry resolved from the current directory.
+    local_agents = target_path / "agents"
+    registry = AgentRegistry(local_agents) if local_agents.exists() else _get_registry()
+    installer = AgentInstaller(registry)
+
+    installed = installer.list_installed_agents(target_path)
+    if not installed:
+        click.echo("No agents installed in this project — nothing to document.")
+        click.echo("  Run: kaizen-agentic install <agents>")
+        return
+
+    agents = [a for a in (registry.get_agent(n) for n in installed) if a is not None]
+    section = render_installed_agents_section(agents)
+
+    claude_md = target_path / "CLAUDE.md"
+    current = claude_md.read_text() if claude_md.exists() else ""
+    updated = upsert_installed_agents_section(current, section)
+
+    if check:
+        if updated != current:
+            click.echo(f"❌ CLAUDE.md is out of date: {claude_md}")
+            click.echo("   Run: kaizen-agentic docs generate")
+            sys.exit(1)
+        click.echo(f"✅ CLAUDE.md is up to date ({len(agents)} agents)")
+        return
+
+    if updated == current:
+        click.echo(f"CLAUDE.md already up to date ({len(agents)} agents)")
+        return
+
+    claude_md.write_text(updated)
+    click.echo(f"Updated Installed Agents section ({len(agents)} agents): {claude_md}")
+
+
 def _project_root(target: str) -> Path:
     return Path(target).resolve()