tegwick
08df3a4697
Some checks failed
ci / test (push) Failing after 44s
- 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
131 lines
5.3 KiB
Markdown
131 lines
5.3 KiB
Markdown
---
|
|
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).
|