kaizen-agentic/docs/integrations/customer-engagement-playbook.md

# Customer Engagement Playbook v1 (supplier)

How kaizen-agentic supports a **customer engagement repo** for **improvement
loops** (reference:
[coulomb-loop](https://forgejo.coulomb.social/coulomb/coulomb-loop)). Second loop
engagements should copy [customer-engagement-repo-layout.md](customer-engagement-repo-layout.md)
and complete the checklist in one session.

**Staffed Role engagements** (host-operator, forward-deployed agency) use a
different tree — see [forward-deployed-engagement-playbook.md](forward-deployed-engagement-playbook.md)
and [ADR-007](../adr/ADR-007-forward-deployed-engagement-convention.md).

## Roles

| Repo | Role |
|------|------|
| Customer (coulomb-loop) | Roster, ActivityDefinition copies, cadence policy, loop health |
| Supplier (kaizen-agentic) | Agents, CLI, integration contracts, this playbook |
| Target repos | `.kaizen/` state (schedule, memory, metrics) |
| activity-core | Cron + event orchestration, task creation |

## Bootstrap checklist

### 1. Customer repo

- 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=<customer>`
- 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)

```bash
kaizen-agentic schedule init --engagement <customer-slug> \
  --agents coach,optimization --bootstrap-cadence hourly
kaizen-agentic schedule validate
kaizen-agentic memory init coach
kaizen-agentic memory init optimization
```

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)

```bash
kaizen-agentic metrics record <agent> --success --time <s> --quality <0-1>
kaizen-agentic metrics record <agent> --success --time <s> --quality <0-1> --emit-event
```

Requires `pip install 'kaizen-agentic[events]'` for `--emit-event`.

### 4. activity-core

- 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. Use atomic promote to
align all three layers (cadence.yml, activity-definitions, fleet schedule.yml,
activity-core sync):

```bash
kaizen-agentic schedule promote \
  --engagement-repo /path/to/customer-loop \
  --engagement <slug> \
  --to-phase operate \
  --activity-core /path/to/activity-core
```

Dry-run: `--dry-run`. Repair fleet drift after a partial promotion: `--fleet-only`.

Legacy per-layer commands still work:

```bash
kaizen-agentic schedule init --engagement <slug> --bootstrap-cadence daily --force
kaizen-agentic schedule init --engagement <slug> --bootstrap-cadence weekly --force
```

## Reference implementation

- Customer: [coulomb-loop INTENT](https://forgejo.coulomb.social/coulomb/coulomb-loop/src/branch/main/INTENT.md)
- Supplier workplan: [KAIZEN-WP-0008](../../workplans/KAIZEN-WP-0008-coulomb-loop-supplier-engagement.md)
- Convention: [ADR-006](../adr/ADR-006-customer-engagement-convention.md)

## Related

- [INTEGRATION_PATTERNS.md](../INTEGRATION_PATTERNS.md) Pattern 2
- [activity-core-handoff-wp0006.md](activity-core-handoff-wp0006.md)