tegwick
0c2df43a2f
Some checks failed
ci / test (push) Failing after 13m58s
Orchestrates cadence.yml, activity-definitions, fleet schedule.yml, and activity-core sync in one command. Supports --dry-run and --fleet-only for repairing partial promotions.
99 lines
3.9 KiB
Markdown
99 lines
3.9 KiB
Markdown
# Customer Engagement Playbook v1 (supplier)
|
||
|
||
How kaizen-agentic supports a **customer engagement repo** (reference:
|
||
[coulomb-loop](https://gitea.coulomb.social/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, 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://gitea.coulomb.social/coulomb/coulomb-loop/src/branch/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
|
||
|
||
- [INTEGRATION_PATTERNS.md](../INTEGRATION_PATTERNS.md) Pattern 2
|
||
- [activity-core-handoff-wp0006.md](activity-core-handoff-wp0006.md)
|