From 4a7f5b2b7d1051dcb1af3e4418e9a8331cbfd062 Mon Sep 17 00:00:00 2001 From: tegwick Date: Tue, 16 Jun 2026 02:21:36 +0200 Subject: [PATCH] plan: add WP-0005 adoption polish and fleet parity (v1.2.0) Draft workplan with 16 tasks across publish verification, install doc sync, packaged agent parity, CI hardening, and ecosystem handoff. Refresh TODO.md and SCOPE.md; register State Hub workstream. --- SCOPE.md | 4 +- TODO.md | 49 ++--- .../kaizen-agentic-WP-0005-adoption-parity.md | 188 ++++++++++++++++++ 3 files changed, 207 insertions(+), 34 deletions(-) create mode 100644 workplans/kaizen-agentic-WP-0005-adoption-parity.md diff --git a/SCOPE.md b/SCOPE.md index 8eb957b..73a41d6 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -74,7 +74,7 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE - Implementation: 20 agents, full CLI (`metrics`, `memory`, `feedback`), agency memory + ADR-004 metrics + optimizer wiring - Stability: CLI stable (Click workaround in place); Gitea CI on main; publish workflow on `v*` tags - Usage: internal dev projects and Custodian MCP hub-wide; pip install via Gitea extra index -- Active work: none — propose **WP-0005** for v1.2.0 (doc sync, packaged fleet parity, adoption polish) +- Active work: **WP-0005** (adoption polish, fleet parity, publish verification → v1.2.0) --- @@ -163,5 +163,5 @@ keywords: [kaizen, intent, template, optimization, digital-talent-agency] ## Notes -- `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` (16 files) is what pip installs ship — coach, sys-medic, scope-analyst, and optimization are not yet bundled +- `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` must stay in sync (enforced in WP-0005 T09–T10) - Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality diff --git a/TODO.md b/TODO.md index 38ab5f3..8166e7a 100644 --- a/TODO.md +++ b/TODO.md @@ -10,42 +10,27 @@ The structure organizes **future tasks** by their impact, just as a changelog or ## [Unreleased] - *Active Vibe-Coding State* 💡 -Tasks moved to workplan: `workplans/kaizen-agentic-WP-0001-community-engagement.md` -Hub workstream: `kaizen-wp-0001-community-engagement` (8 tasks, all todo) +Tasks in workplan: `workplans/kaizen-agentic-WP-0005-adoption-parity.md` (v1.2.0) + +### To Add +* **Gitea publish pipeline verification** — secrets + workflow smoke test +* **`make agents-sync-package`** — keep `data/agents/` aligned with `agents/` +* **Install doc sweep** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION + +### To Refactor +* **CI lint gate** — flake8 on `src/` in Gitea Actions +* **Makefile install hints** — point at Gitea registry or dev install + +### Deferred to WP-0006 (v1.3.0) +* Interactive agent selection wizard +* Agent template schema validation in `validate` +* Documentation generation from agent metadata *** -## [1.1.0] - Community Engagement and Advanced Automation - *Next Planned Increment* +## [1.1.0] - Community Engagement — *Shipped 2026-06-18* -This version focuses on community engagement, advanced automation, and enhanced user experience. - -### To Add -* **Developer feedback mechanisms** for easy collection of user feedback and suggestions -* **Interactive agent selection** wizard for new projects -* **GitHub Actions workflows** for CI/CD automation -* **Agent metrics and telemetry** system for usage tracking and optimization -* **Agent template validation** system with schema enforcement -* **Documentation generation** automation from agent metadata -* **Community contribution guidelines** and contributor onboarding - -### To Refactor -* **CLI error handling** with more user-friendly messages and suggestions -* **Performance optimization** for handling large numbers of agents -* **Installation process** with progress indicators and detailed feedback - -### To Fix -* **Cross-platform compatibility** testing and fixes for Windows/macOS environments -* **Edge case handling** in dependency resolution algorithms -* **Memory usage optimization** for large-scale agent installations - -### To Secure -* **Agent integrity verification** with checksums and validation -* **Sandboxed agent execution** for security-sensitive environments -* **Configuration file validation** to prevent malicious modifications - -### To Remove -* **Legacy installation methods** that are no longer supported -* **Deprecated CLI options** and maintain backward compatibility warnings +See `CHANGELOG.md` [1.1.0] and `workplans/kaizen-agentic-WP-0001-community-engagement.md`. *** diff --git a/workplans/kaizen-agentic-WP-0005-adoption-parity.md b/workplans/kaizen-agentic-WP-0005-adoption-parity.md new file mode 100644 index 0000000..491c1f0 --- /dev/null +++ b/workplans/kaizen-agentic-WP-0005-adoption-parity.md @@ -0,0 +1,188 @@ +--- +id: KAIZEN-WP-0005 +type: workplan +title: "Adoption Polish and Fleet Parity (v1.2.0)" +domain: custodian +repo: kaizen-agentic +status: active +owner: kaizen-agentic +topic_slug: custodian +state_hub_workstream_id: 88c7b3e6-be98-480c-b47b-936e74a1a31b +created: "2026-06-16" +updated: "2026-06-16" +--- + +# KAIZEN-WP-0005 — Adoption Polish and Fleet Parity + +**Status:** active +**Owner:** kaizen-agentic +**Repo:** kaizen-agentic +**Target version:** 1.2.0 +**Depends on:** WP-0001 (v1.1.0 ship), WP-0004 (ecosystem integration docs) + +## Goal + +Close adoption gaps after the v1.1.0 release: verify the Gitea publish pipeline, +align all install documentation with the Coulomb registry, enforce packaged-agent +parity with `agents/`, and harden CI so v1.2.0 ships with confidence. + +WP-0001 through WP-0004 delivered features; WP-0005 makes them **discoverable, +installable, and maintainable** for ecosystem consumers. + +--- + +## Part 1 — Publish Pipeline Verification + +Confirm tag-triggered publication works end-to-end before the v1.2.0 cut. + +### Tasks + +- [ ] T01 — Configure `GITEA_PACKAGE_USER` and `GITEA_PACKAGE_TOKEN` secrets in Gitea repo settings (document checklist in `docs/PACKAGE_RELEASE.md`) +- [ ] T02 — Smoke-test `.gitea/workflows/publish-python-package.yml` via `workflow_dispatch` +- [ ] T03 — Add pre-tag release checklist to `docs/PACKAGE_RELEASE.md` (secrets, `make package-check`, tag format) + +### Definition of done + +- Publish workflow succeeds without manual `twine upload` +- `docs/PACKAGE_RELEASE.md` documents the full operator path + +--- + +## Part 2 — Install Documentation Sync + +Several docs still show bare `pip install kaizen-agentic` (pre-Gitea registry). + +### Tasks + +- [ ] T04 — Update `docs/HELLO_WORLD_TUTORIAL.md` install sections (Gitea extra index + pipx) +- [ ] T05 — Update `docs/CLI_CHEAT_SHEET.md` install sections +- [ ] T06 — Update `docs/AGENT_DISTRIBUTION.md` install and distribution sections +- [ ] T07 — Update Makefile `agents-*` fallback messages to point at dev install or `PACKAGE_RELEASE.md` +- [ ] T08 — Cross-link `CONTRIBUTING.md` post-pull reinstall with `docs/PACKAGE_RELEASE.md` + +### Definition of done + +- No consumer-facing doc implies public pypi.org is the primary install path +- All install examples use env-var credentials (no committed tokens) + +--- + +## Part 3 — Packaged Fleet Parity + +Ensure `pip install` ships the same agent fleet as `agents/`. + +### Tasks + +- [ ] T09 — Add `make agents-sync-package` (copy `agents/agent-*.md` → `data/agents/`) with dry-run mode +- [ ] T10 — Add pytest or `release-check` step verifying `agents/` and `data/agents/` file sets match +- [x] T11 — Refresh `SCOPE.md` notes and agent-count references (currently stale at 16 vs 20) + +### Definition of done + +- `make release-check` fails when packaged agents drift from source +- Wheel contents match canonical `agents/` directory + +--- + +## Part 4 — Release Hygiene and CI + +Prepare v1.2.0 versioning and strengthen automated gates. + +### Tasks + +- [x] T12 — Refresh `TODO.md`: archive 1.1.0 items, point `[Unreleased]` at this workplan +- [ ] T13 — Open `CHANGELOG.md` `[Unreleased]` section for v1.2.0 tracking +- [ ] T14 — Extend `.gitea/workflows/ci.yml` with flake8 (`release-check` lint subset on `src/`) + +### Definition of done + +- `TODO.md` reflects current vibe-coding state only +- CI catches lint regressions before merge + +--- + +## Part 5 — Ecosystem Handoff (coordination) + +Cross-repo follow-through from WP-0004; no foreign code in this repo. + +### Tasks + +- [ ] T15 — Document activity-core ActivityDefinition registration steps in `docs/INTEGRATION_PATTERNS.md` (handoff checklist for activity-core owners) +- [ ] T16 — Verify bidirectional Helix correlation doc link with agentic-resources (close WP-0004 T01 loop if gap remains) + +### Definition of done + +- Operators know how to activate the three ActivityDefinitions committed under `docs/integrations/activity-definitions/` +- Helix correlation is linked from both repos + +--- + +## Sequencing + +``` +Part 1 (T01–T03) ──→ can run in parallel with Part 2 + │ +Part 2 (T04–T08) ──→ Part 4 (T12–T13) doc hygiene + │ +Part 3 (T09–T11) ──→ gates v1.2.0 tag + │ +Part 4 (T14) ──→ before v1.2.0 merge freeze + │ +Part 5 (T15–T16) ──→ non-blocking; parallel with Parts 2–4 +``` + +Estimated effort: 2–4 sessions. + +--- + +## Out of Scope + +- Public pypi.org publication (optional; Gitea registry remains primary) +- Interactive agent selection wizard (defer to WP-0006) +- Full `KaizenAgentTemplate.md` schema enforcement in `validate` (defer to WP-0006) +- Automated documentation generation from agent metadata +- Owning activity-core, agentic-resources, or artifact-store code + +--- + +## Success Criteria + +1. Tag `v1.2.0` triggers Gitea PyPI publish without manual intervention. +2. A new consumer can install from docs alone (no tribal knowledge about extra index). +3. Packaged wheel agent fleet cannot drift silently from `agents/`. +4. WP-0004 ecosystem artifacts have clear operator handoff paths. + +--- + +## State Hub Task IDs + +| Code | UUID | +|------|------| +| T01 | 1fb6b04e-0854-4cc9-83c7-5abf85fe5bff | +| T02 | bdb9e463-bdfb-405c-afc4-e93a7d58a18b | +| T03 | 6a2132e7-8b3f-4960-a5e8-85bad81e8b13 | +| T04 | 553cba3a-dafa-483a-9200-70ac3f5eb2d7 | +| T05 | 7e6663a5-fedf-4b1c-acd9-6df6b43d8a12 | +| T06 | fe553788-357f-45c4-8400-f764f68c1cde | +| T07 | b131ff67-fe21-4d95-904b-6a0b916c5502 | +| T08 | 07dd4d25-250c-455c-8363-49269d2ee59f | +| T09 | 7437cedd-5f7e-4c4d-9142-4f67470c9e52 | +| T10 | ddbe2114-7a47-48fd-a145-b22dca2b581a | +| T11 | 5417524f-03c0-40ed-a48b-a7906e6daf8f | +| T12 | 5cfad56c-2664-4b2d-b5f9-4792c958c9a2 | +| T13 | fbca9be4-3d2b-4989-baaf-97e6926bdc66 | +| T14 | a6966cfa-ca59-4087-8989-2870dc69b13f | +| T15 | fbf3f1a8-4818-473e-ae0d-cd80118e5319 | +| T16 | 37679ce7-dcb6-42a4-820d-cf8b32c2a248 | + +**Hub workstream:** `kaizen-wp-0005-adoption-parity` (`88c7b3e6-be98-480c-b47b-936e74a1a31b`) + +--- + +## Notes + +- Deferred from TODO.md [1.1.0]: agent selection wizard, template schema validation, + doc generation automation → candidate **WP-0006** (v1.3.0) +- `make agents-update` updates project-installed agents via CLI; it does **not** + sync `agents/` → `data/agents/` — T09 addresses that gap explicitly +- Part 1 T01 requires Gitea UI access (human step); automation cannot set secrets