From dda49cd821508cad7d3ff072ed9f460441a41edd Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 18 Jun 2026 11:02:09 +0200 Subject: [PATCH] feat: complete KAIZEN-WP-0008 customer engagement supplier deliverables Add repo layout doc, ADR-006 convention, playbook v1 with supplier-notes, override manifest design, and wiki integration. Mark workplan done (10/10). --- CHANGELOG.md | 3 + .../ADR-006-customer-engagement-convention.md | 74 +++++++++++++++++++ .../activity-definition-override-manifest.md | 72 ++++++++++++++++++ .../customer-engagement-playbook.md | 60 +++++++++------ .../customer-engagement-repo-layout.md | 65 ++++++++++++++++ wiki/EcosystemIntegration.md | 11 +++ ...P-0008-coulomb-loop-supplier-engagement.md | 31 ++++---- 7 files changed, 280 insertions(+), 36 deletions(-) create mode 100644 docs/adr/ADR-006-customer-engagement-convention.md create mode 100644 docs/integrations/activity-definition-override-manifest.md create mode 100644 docs/integrations/customer-engagement-repo-layout.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 31e4c17..c1744b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 `pip install 'kaizen-agentic[events]'`) - **`schedule init --engagement`** — bootstrap presets for customer engagements (`--bootstrap-cadence hourly|daily|weekly`) +- **ADR-006** — customer engagement convention (supplier/customer split, playbook) +- **Playbook v1** — `docs/integrations/customer-engagement-playbook.md`, + `customer-engagement-repo-layout.md`, override manifest design - **Event contract** — `docs/integrations/kaizen-metrics-recorded-event.md` - **Engagement handoff** — `docs/integrations/activity-core-handoff-engagement.md` diff --git a/docs/adr/ADR-006-customer-engagement-convention.md b/docs/adr/ADR-006-customer-engagement-convention.md new file mode 100644 index 0000000..d94dff2 --- /dev/null +++ b/docs/adr/ADR-006-customer-engagement-convention.md @@ -0,0 +1,74 @@ +# ADR-006: Customer Engagement Convention + +**Status:** accepted +**Date:** 2026-06-18 +**Deciders:** kaizen-agentic maintainers (supplier) +**Customer reference:** coulomb-loop / LOOP-WP-0000 + +## Context + +Coulomb's `coulomb-loop` engagement introduced a **customer/supplier split**: +the customer repo holds contracts and operations; `kaizen-agentic` ships agents +and CLI; target repos hold `.kaizen/` runtime state. We need a durable convention +so the second customer engagement reuses ≤50% of coulomb-loop setup effort. + +## Decision + +### 1. Repo roles + +| Role | Owns | +|------|------| +| **Customer engagement repo** | INTENT, workplans, ADRs, rosters, ActivityDefinition copies, loop health | +| **Supplier (kaizen-agentic)** | Agent prompts, CLI, integration specs, playbook, supplier workplans | +| **Target repos** | `.kaizen/schedule.yml`, `agents/`, `metrics/`, memory | +| **activity-core** | Cron/event orchestration, resolvers, task creation | + +### 2. `.kaizen/` placement + +Project-scoped kaizen state **never** lives in the customer engagement repo. +It lives only in repos where agents execute (fleet pilots). + +### 3. Supplier CLI engagement mode + +```bash +kaizen-agentic schedule init --engagement \ + --agents coach,optimization --bootstrap-cadence hourly +``` + +Writes bootstrap schedule with engagement comment and hourly cron presets. +See [customer-engagement-playbook.md](../integrations/customer-engagement-playbook.md). + +### 4. Event emission (opt-in) + +```bash +kaizen-agentic metrics record --success --time --quality <0-1> --emit-event +``` + +Publishes `kaizen.metrics.recorded` for activity-core event definitions. +Default off for backward compatibility. + +### 5. Playbook lifecycle + +1. **Bootstrap** — customer LOOP-WP-0000; supplier KAIZEN-WP-0008 Part 1 +2. **Smoke** — hourly E2E on pilot roster (LOOP-WP-0001) +3. **Automate** — emit-event, activity-core definitions enabled incrementally +4. **Generalize** — supplier-notes → playbook v1; ADR-006 + layout docs +5. **Second customer** — copy layout; swap roster and definitions + +### 6. ActivityDefinition ownership + +Bootstrap uses **customer-owned copies** (coulomb DEC-003 option A). +Hybrid override manifest (option C) is design-only — see +[activity-definition-override-manifest.md](../integrations/activity-definition-override-manifest.md). + +## Consequences + +- New engagements follow [customer-engagement-repo-layout.md](../integrations/customer-engagement-repo-layout.md) +- Supplier friction is logged in customer `loops/*/supplier-notes.md` and absorbed into playbook +- activity-core handoff requirements are documented per engagement wave + +## Related + +- coulomb-loop `docs/adr/ADR-002-customer-supplier-boundary.md` +- [ADR-005](ADR-005-scheduled-agent-execution.md) — schedule contract +- [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md) diff --git a/docs/integrations/activity-definition-override-manifest.md b/docs/integrations/activity-definition-override-manifest.md new file mode 100644 index 0000000..4fcb3fa --- /dev/null +++ b/docs/integrations/activity-definition-override-manifest.md @@ -0,0 +1,72 @@ +# ActivityDefinition Override Manifest (design) + +**Status:** design-only (DEC-003 option C future) +**Implements:** KAIZEN-WP-0008 T08 +**Runtime:** none in v1 — customer-owned copies (option A) during bootstrap + +## Problem + +Customer repos copy supplier ActivityDefinitions and tune cron, labels, and +`enabled` flags. When supplier templates change, manual merge is error-prone. +A manifest declares **source + overrides** without duplicating full definition bodies. + +## Proposed file + +`activity-definitions/manifest.yaml` in the customer repo: + +```yaml +version: "1" +supplier_repo: kaizen-agentic +supplier_path: docs/integrations/activity-definitions +engagement: coulomb-loop + +definitions: + - supplier_id: kaizen-weekly-coach-orientation + customer_id: coulomb-hourly-coach-orientation + source: ../../kaizen-agentic/docs/integrations/activity-definitions/weekly-coach-orientation.md + overrides: + id: coulomb-hourly-coach-orientation + name: Hourly Kaizen Coach Orientation (coulomb-loop bootstrap) + owner: coulomb-loop + governance: coulomb_social + enabled: true + trigger: + cron_expression: "15 * * * *" + context_sources: + - params: + roster: /home/worsch/coulomb-loop/loops/kaizen-stack/roster.yaml + cadence: daily + + - supplier_id: kaizen-low-success-rate-review + customer_id: coulomb-low-success-rate-review + overrides: + enabled: false + owner: coulomb-loop +``` + +## Merge rules (future tooling) + +1. Parse supplier definition markdown (frontmatter + body) +2. Deep-merge `overrides` (customer wins on conflict) +3. Write customer copy to `activity-definitions/.md` +4. `sync_activity_definitions` reads customer copies only (unchanged today) + +## Ownership + +| Layer | Owner | +|-------|-------| +| Manifest schema | kaizen-agentic (supplier ADR/extension) | +| Manifest instance | customer repo | +| Merge CLI | TBD — `coulomb-loop` or `activity-core` | +| Sync runtime | activity-core (unchanged) | + +## Bootstrap path (today) + +Use **option A**: hand-copy definitions, edit cron/labels, track drift in +`loops/kaizen-stack/supplier-notes.md`. Revisit manifest when a second customer +engagement starts. + +## Related + +- coulomb-loop `docs/decisions/DEC-003-activity-definition-ownership.md` +- [customer-engagement-playbook.md](customer-engagement-playbook.md) diff --git a/docs/integrations/customer-engagement-playbook.md b/docs/integrations/customer-engagement-playbook.md index 9e2fddc..03a0278 100644 --- a/docs/integrations/customer-engagement-playbook.md +++ b/docs/integrations/customer-engagement-playbook.md @@ -1,14 +1,16 @@ -# Customer Engagement Playbook (supplier) +# Customer Engagement Playbook v1 (supplier) -How kaizen-agentic supports a **customer engagement repo** (e.g. coulomb-loop) -that orchestrates improvement loops across a pilot roster. +How kaizen-agentic supports a **customer engagement repo** (reference: +[coulomb-loop](https://gitea.example/coulomb/coulomb-loop)). Second engagements +should copy [customer-engagement-repo-layout.md](customer-engagement-repo-layout.md) +and complete the checklist in one session. ## Roles | Repo | Role | |------|------| | Customer (coulomb-loop) | Roster, ActivityDefinition copies, cadence policy, loop health | -| Supplier (kaizen-agentic) | Agents, CLI, integration contracts | +| Supplier (kaizen-agentic) | Agents, CLI, integration contracts, this playbook | | Target repos | `.kaizen/` state (schedule, memory, metrics) | | activity-core | Cron + event orchestration, task creation | @@ -16,10 +18,12 @@ that orchestrates improvement loops across a pilot roster. ### 1. Customer repo -- Register engagement in state-hub -- Commit pilot roster (`loops/kaizen-stack/roster.yaml`) -- Copy ActivityDefinitions to `activity-definitions/` -- Enable definitions incrementally (metrics → coach → optimization) +- Register engagement in state-hub (`register_project.sh`) +- Write `INTENT.md`, `SCOPE.md`, LOOP-WP-0000–0004 workplans +- Accept ADRs and DEC-* decisions; run `fix-consistency REPO=` +- Copy ActivityDefinitions to `activity-definitions/` (DEC-003 option A) +- Register reuse-surface capability (LOOP-WP-0000 T08) +- Enable definitions incrementally: metrics → coach → optimization ### 2. Target repos (per pilot) @@ -31,7 +35,7 @@ kaizen-agentic memory init coach kaizen-agentic memory init optimization ``` -Hourly bootstrap writes `cadence: daily` with hourly `cron` overrides — see +Hourly bootstrap uses `cadence: daily` with hourly `cron` overrides — see [activity-core-handoff-engagement.md](activity-core-handoff-engagement.md) R2. ### 3. Session close (each agent run) @@ -41,26 +45,40 @@ kaizen-agentic metrics record --success --time --quality <0-1> kaizen-agentic metrics record --success --time --quality <0-1> --emit-event ``` +Requires `pip install 'kaizen-agentic[events]'` for `--emit-event`. + ### 4. activity-core -Hand off [activity-core-handoff-engagement.md](activity-core-handoff-engagement.md) -requirements before enabling event-driven quality escalation. +- Sync definitions from customer `activity-definitions/` +- Implement handoff requirements in [activity-core-handoff-engagement.md](activity-core-handoff-engagement.md) +- Manual trigger smoke before enabling hourly crons + +## Lessons from coulomb-loop (supplier-notes absorbed) + +| Observation | Resolution (shipped) | +|-------------|----------------------| +| `schedule init` weekly defaults unsuitable for bootstrap | `schedule init --engagement --bootstrap-cadence hourly` (KAIZEN-WP-0008 T04) | +| No metrics event for LOOP-WP-0002 | `metrics record --emit-event` (T03) | +| `metrics optimize` with 0 records confusing during bootstrap | Expected — document in bootstrap log; optimizer needs ≥10 records for recommendations | +| ActivityDefinition drift from supplier templates | Customer copies (DEC-003 A); hybrid manifest design for v2 ([override manifest](activity-definition-override-manifest.md)) | +| Rotation saturation signals | Future: `metrics rotation-signals` CLI (ADR-004 follow-on) | ## Cadence promotion -Customer regulator (LOOP-WP-0004) approves promotion. Re-init or patch schedules: +Customer regulator (LOOP-WP-0004) approves promotion. Re-init schedules: ```bash -# Stabilize phase -kaizen-agentic schedule init --engagement \ - --bootstrap-cadence daily --force - -# Operate phase -kaizen-agentic schedule init --engagement \ - --bootstrap-cadence weekly --force +kaizen-agentic schedule init --engagement --bootstrap-cadence daily --force +kaizen-agentic schedule init --engagement --bootstrap-cadence weekly --force ``` +## Reference implementation + +- Customer: [coulomb-loop INTENT](https://gitea.example/coulomb/coulomb-loop/blob/main/INTENT.md) +- Supplier workplan: [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md) +- Convention: [ADR-006](../adr/ADR-006-customer-engagement-convention.md) + ## Related -- [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md) -- coulomb-loop `INTENT.md` and `workplans/LOOP-WP-*` +- [INTEGRATION_PATTERNS.md](../INTEGRATION_PATTERNS.md) Pattern 2 +- [activity-core-handoff-wp0006.md](activity-core-handoff-wp0006.md) diff --git a/docs/integrations/customer-engagement-repo-layout.md b/docs/integrations/customer-engagement-repo-layout.md new file mode 100644 index 0000000..63de3f0 --- /dev/null +++ b/docs/integrations/customer-engagement-repo-layout.md @@ -0,0 +1,65 @@ +# Customer Engagement Repo Layout + +Contract for a **customer engagement repository** that orchestrates kaizen +improvement loops across a fleet roster. Reference implementation: +[coulomb-loop](https://gitea.example/coulomb/coulomb-loop) (`coulomb_social` domain). + +Supplier agents and CLI live in `kaizen-agentic`. Runtime `.kaizen/` state lives +in **target repos**, not in the customer repo. + +## Directory tree + +``` +customer-repo/ +├── INTENT.md # Engagement purpose, loop map, cadence policy summary +├── SCOPE.md # In/out of scope; supplier boundaries +├── CLAUDE.md # Session protocol + rules includes +├── .claude/rules/ # repo-identity, architecture, workplan-convention, … +├── workplans/ +│ ├── -WP-0000-* # Bootstrap (registration, ADRs, decisions) +│ ├── -WP-0001-* # Primary improvement stack +│ ├── -WP-0002-* # Reactive quality escalation +│ ├── -WP-0003-* # Registry / orientation hygiene +│ └── -WP-0004-* # Loop regulator (cadence promotion, rotation) +├── docs/ +│ ├── adr/ # Customer ADRs (boundary, cadence, ownership) +│ ├── decisions/ # DEC-* proposals awaiting operator acceptance +│ └── integrations/ # activity-core handoff, event payloads +├── history/ # Assessments, milestone snapshots +├── activity-definitions/ # Customer-owned copies (DEC-003 option A) +├── loops/ +│ └── / +│ ├── roster.yaml # Pilot + expansion_queue + saturated +│ ├── bootstrap-log.md # E2E cycle evidence +│ ├── supplier-notes.md # Friction fed back to kaizen-agentic +│ └── rotation-policy.yml # ADR-004 diminishing-returns (optional) +└── registry/ # reuse-surface capability index (engagement D0) + ├── indexes/capabilities.yaml + └── capabilities/ +``` + +## Naming + +| Artifact | coulomb-loop example | +|----------|----------------------| +| Workplan prefix | `LOOP-WP-NNNN` | +| Hub topic slug | `coulomb_social` | +| Engagement slug in schedules | `coulomb-loop` | +| Supplier workplan | `KAIZEN-WP-0008` (kaizen-agentic) | + +## What does not live here + +- `agents/agent-*.md` — supplier (`kaizen-agentic`) +- `.kaizen/schedule.yml` on customer repo — target fleet repos only +- Temporal workers / resolvers — `activity-core` +- state-hub service code — `the-custodian` + +## Bootstrap sequence + +See [customer-engagement-playbook.md](customer-engagement-playbook.md). + +## Related + +- coulomb-loop `docs/adr/ADR-002-customer-supplier-boundary.md` +- [ADR-006](../adr/ADR-006-customer-engagement-convention.md) +- [KAIZEN-WP-0008](../../workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md) diff --git a/wiki/EcosystemIntegration.md b/wiki/EcosystemIntegration.md index d0d30a0..3e71625 100644 --- a/wiki/EcosystemIntegration.md +++ b/wiki/EcosystemIntegration.md @@ -111,6 +111,17 @@ runs `kaizen-agentic schedule prepare `. **Workplan:** KAIZEN-WP-0004 Part 2 + KAIZEN-WP-0006. Patterns: [docs/INTEGRATION_PATTERNS.md](../docs/INTEGRATION_PATTERNS.md). +**Customer engagement (WP-0008, ADR-006)** — a customer repo (e.g. coulomb-loop) +orchestrates loops across a fleet roster; supplier ships playbook + CLI: + +- [customer-engagement-playbook](../docs/integrations/customer-engagement-playbook.md) +- [customer-engagement-repo-layout](../docs/integrations/customer-engagement-repo-layout.md) +- [ADR-006](../docs/adr/ADR-006-customer-engagement-convention.md) +- CLI: `schedule init --engagement`, `metrics record --emit-event` +- activity-core handoff: [activity-core-handoff-engagement](../docs/integrations/activity-core-handoff-engagement.md) + +Reference customer: coulomb-loop `INTENT.md` (coulomb_social domain). + ### artifact-store (P1) **Evidence retention** — durable registry for generated outputs. diff --git a/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md b/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md index 9f3019a..0795620 100644 --- a/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md +++ b/workplans/kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md @@ -4,7 +4,7 @@ type: workplan title: "Coulomb-loop supplier engagement (customer-repo playbook)" domain: custodian repo: kaizen-agentic -status: active +status: done owner: kaizen-agentic topic_slug: custodian customer_repo: coulomb-loop @@ -15,7 +15,7 @@ depends_on: - KAIZEN-WP-0004 tasks: - id: T01 - status: todo + status: done title: Document customer engagement repo layout from coulomb-loop reference - id: T02 status: done @@ -30,26 +30,26 @@ tasks: status: done title: Support pilot schedule init on kaizen-agentic the-custodian activity-core - id: T06 - status: todo + status: done title: Draft ADR-006 customer engagement convention - id: T07 - status: todo + status: done title: Absorb coulomb-loop supplier-notes into playbook v1 - id: T08 - status: todo + status: done title: ActivityDefinition override manifest design for hybrid sync - id: T09 - status: todo + status: done title: Tests for emit-event and engagement init - id: T10 - status: todo + status: done title: Update CHANGELOG wiki and cross-link coulomb-loop INTENT state_hub_workstream_id: "80f473eb-d052-4f50-a633-806f03c469be" --- # KAIZEN-WP-0008 — Coulomb-loop Supplier Engagement -**Status:** active +**Status:** done **Owner:** kaizen-agentic (supplier) **Customer:** `coulomb-loop` (coulomb_social domain) **Depends on:** WP-0006 (schedule contract), WP-0004 (activity-core integration) @@ -96,7 +96,7 @@ Part 3 (T07–T08, T10) ── after LOOP-WP-0004 supplier-notes available ```task id: KAIZEN-WP-0008-T01 -status: todo +status: done priority: high state_hub_task_id: "177bb16c-6239-43f2-8d99-f4498c31d74a" ``` @@ -206,7 +206,7 @@ Writes hourly crons per ADR-003; documents engagement slug in schedule comment. ```task id: KAIZEN-WP-0008-T06 -status: todo +status: done priority: medium state_hub_task_id: "5c06cdd9-655d-4837-b725-1f89b83db6d4" ``` @@ -218,12 +218,13 @@ split, `.kaizen/` placement in target repos, playbook lifecycle. ```task id: KAIZEN-WP-0008-T09 -status: todo +status: done priority: medium state_hub_task_id: "f45077ea-5d24-4a85-bac2-ab9a3f61c20b" ``` -Unit tests: `--emit-event` payload shape; `--engagement` schedule output. +Covered by `tests/test_metrics_emit_event.py` and `tests/test_schedule_cli.py` +(engagement init + module presets). --- @@ -233,7 +234,7 @@ Unit tests: `--emit-event` payload shape; `--engagement` schedule output. ```task id: KAIZEN-WP-0008-T07 -status: todo +status: done priority: low state_hub_task_id: "0ef49fb5-af2f-4adf-aa90-1ea2cf389d00" ``` @@ -245,7 +246,7 @@ Target: second customer can copy template repo and run checklist in one session. ```task id: KAIZEN-WP-0008-T08 -status: todo +status: done priority: low state_hub_task_id: "c9bee570-89b5-43e5-aabc-23c7dcc4e30c" ``` @@ -257,7 +258,7 @@ definition id → customer cron/labels/enabled overrides. No runtime in v1. ```task id: KAIZEN-WP-0008-T10 -status: todo +status: done priority: low state_hub_task_id: "052a592b-ae7c-4213-9e09-eb8b37119d5e" ```