# 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.coulomb.social/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/
│   ├── <PREFIX>-WP-0000-*    # Bootstrap (registration, ADRs, decisions)
│   ├── <PREFIX>-WP-0001-*    # Primary improvement stack
│   ├── <PREFIX>-WP-0002-*    # Reactive quality escalation
│   ├── <PREFIX>-WP-0003-*    # Registry / orientation hygiene
│   └── <PREFIX>-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/
│   └── <loop-id>/
│       ├── 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)