Bootstrap coulomb-loop engagement: governance, loops, and activity definitions.

Register with state-hub, accept DEC-001–004 and ADR-004 rotation policy, scaffold
pilot roster, hourly ActivityDefinition copies, and bootstrap log after schedule
init on three custodian pilot repos.

.claude/rules/agents.md

@@ -0,0 +1,20 @@
+## Kaizen Agents
+
+Specialized agent personas available on demand via the state-hub MCP.
+
+**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
+**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
+
+Common agents:
+
+| Agent | Category | When to use |
+|-------|----------|-------------|
+| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
+| `code-refactoring` | quality | Code quality analysis and safe refactoring |
+| `test-maintenance` | testing | Diagnose and fix failing tests |
+| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
+| `keepaTodofile` | process | Maintain TODO.md during work |
+| `project-management` | process | Track status, determine next steps |
+| `datamodel-optimization` | quality | Optimize dataclasses and data structures |
+
+All 17 agents: call `list_kaizen_agents()` for the full list.

.claude/rules/architecture.md

@@ -0,0 +1,25 @@
+## Architecture
+
+`coulomb-loop` is a **markdown-first engagement layer** — no application runtime.
+
+```
+activity-core (cron/event)
+  → state-hub roster + coulomb-loop rosters
+  → tasks on target repos
+  → kaizen-agentic schedule prepare / metrics CLI
+  → coding-agent sessions (supplier agents)
+```
+
+### Layers
+
+| Layer | Repo | Role |
+|-------|------|------|
+| Customer contracts | coulomb-loop | Workplans, ADRs, ActivityDefinition copies, `loops/` |
+| Supplier IP | kaizen-agentic | Agents, CLI, ADR-002–006 |
+| Scheduler | activity-core | Temporal schedules, resolvers |
+| Roster | state-hub | Repo list, workstreams, events |
+| Execution state | target repos | `.kaizen/schedule.yml`, memory, metrics |
+
+### Four loops
+
+See `INTENT.md` and LOOP-WP-0001–0004. LOOP-WP-0004 regulates cadence (ADR-003).

.claude/rules/first-session.md

@@ -0,0 +1,38 @@
+## First Session Protocol
+
+Triggered when `get_domain_summary("coulomb_social")` shows **no workstreams**.
+The project is registered but work has not yet been structured.
+
+**Step 1 — Read, don't write**
+- `~/the-custodian/canon/projects/coulomb_social/project_charter_v0.1.md` — purpose, scope
+- `~/the-custodian/canon/projects/coulomb_social/roadmap_v0.1.md` — planned phases
+- Scan repo root: README, directory structure, existing code or docs
+
+**Step 2 — Survey in-progress work**
+Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
+
+**Step 3 — Propose workstreams to Bernd**
+Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
+roadmap phase. **Wait for approval before creating.**
+
+**Step 4 — Create workplan file first, then DB record (ADR-001)**
+```
+workplans/COULOMB-WP-NNNN-<slug>.md   ← write this first
+```
+Then register in the hub:
+```
+create_workstream(topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", title="...", owner="...", description="...")
+create_task(workstream_id="<id>", title="...", priority="high|medium|low")
+```
+
+**Step 5 — Record the setup**
+```
+add_progress_event(
+    summary="First session: structured coulomb_social into N workstreams, M tasks",
+    event_type="milestone",
+    topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc",
+    detail={"workstreams": [...], "tasks_created": M}
+)
+```
+
+<!-- Delete or archive this file once past first session -->

.claude/rules/repo-boundary.md

@@ -0,0 +1,11 @@
+## Repo boundary
+
+This repo owns **coulomb-loop engagement operations** only. It does not own:
+
+- Kaizen agent definitions → `kaizen-agentic`
+- activity-core resolvers and Temporal workers → `activity-core`
+- State-hub API/MCP → `state-hub` / `the-custodian`
+- reuse-surface CLI and federation hub → `reuse-surface`
+- Target repo `.kaizen/` state → each fleet repo checkout
+
+Cross-repo handoffs are documented in loop workplans and `docs/adr/ADR-002-customer-supplier-boundary.md`.

.claude/rules/repo-identity.md

@@ -0,0 +1,15 @@
+## Repo Identity
+
+**Purpose:** coulomb-loop — Coulomb customer engagement repo for fleet self-improvement loops operated with kaizen-agentic as supplier.
+
+**Domain:** coulomb_social
+**Repo slug:** coulomb-loop
+**Topic ID:** 36c7421b-c537-4723-bf75-42a3ebc6a1dc
+
+**Supplier:** `kaizen-agentic` (agents, CLI, playbook — not merged into this repo)
+
+**Custodian integration:** Registered in state-hub. Workplans use `LOOP-WP` prefix (ADR-001). Sync after workplan edits:
+
+```bash
+cd ~/state-hub && make fix-consistency REPO=coulomb-loop
+```

.claude/rules/session-protocol.md

@@ -0,0 +1,84 @@
+## Session Protocol
+
+State Hub: http://127.0.0.1:8000
+
+**Step 1 — Orient**
+
+Read the offline-safe brief first — it works without a live hub connection:
+```bash
+cat .custodian-brief.md
+```
+Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
+```
+get_domain_summary("coulomb_social")
+```
+If MCP tools are unavailable in the current agent session, use the REST API:
+```bash
+curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
+```
+If the hub is offline: `cd ~/state-hub && make api`
+
+**Step 2 — Check inbox**
+With MCP tools:
+```
+get_messages(to_agent="coulomb-loop", unread_only=True)
+```
+Mark read with `mark_message_read(message_id)`. Reply or act on coordination
+requests before proceeding.
+
+Without MCP tools:
+```bash
+curl -s "http://127.0.0.1:8000/messages/?to_agent=coulomb-loop&unread_only=true" \
+  | python3 -m json.tool
+curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+**Step 3 — Scan workplans**
+```bash
+ls workplans/
+```
+For each file with `status: ready`, `active`, or `blocked`, note pending
+`wait`/`todo`/`progress` tasks.
+
+**Step 4 — Present brief**
+
+1. **Active workstreams** for `coulomb_social` — title, task counts, blocking decisions
+2. **Pending tasks** from `workplans/` + any `[repo:coulomb-loop]` hub tasks
+3. **Goal guidance** — if `goal_guidance` in summary:
+   - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
+   - `alignment_warnings`: flag if active work is not aligned with current goal
+4. **Suggested next action** — highest-priority open item
+5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
+
+If no workstreams: follow First Session Protocol (`first-session.md`).
+
+**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
+
+> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
+> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
+
+**Session close:**
+With MCP tools:
+```
+add_progress_event(summary="...", topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", workstream_id="<uuid>")
+```
+Without MCP tools:
+```bash
+curl -s -X POST http://127.0.0.1:8000/progress/ \
+  -H "Content-Type: application/json" \
+  -d '{"topic_id":"36c7421b-c537-4723-bf75-42a3ebc6a1dc","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
+```
+If workplan files were modified, ensure the local copy is up to date first:
+```bash
+git -C <repo_path> pull --ff-only
+cd ~/state-hub && make fix-consistency REPO=coulomb-loop
+```
+For repos where implementation runs on a remote machine (e.g. CoulombCore),
+use the combined target which pulls before fixing:
+```bash
+cd ~/state-hub && make fix-consistency-remote REPO=coulomb-loop
+```
+**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
+will sync the file to match DB.  **C-16** (repo behind remote) blocks all writes
+until you pull — intentional to prevent clobbering remote progress.

.claude/rules/stack-and-commands.md

@@ -0,0 +1,28 @@
+## Stack and Commands
+
+**Language:** Markdown / YAML coordination artefacts
+**Package manager:** none
+**Test runner:** none
+
+### Essential commands
+
+```bash
+# Sync workplans to state-hub after edits
+cd ~/state-hub && make fix-consistency REPO=coulomb-loop
+
+# Validate reuse-surface registry (when entries exist)
+reuse-surface validate
+
+# Supplier CLI on target repos (not this repo)
+kaizen-agentic schedule validate --target /path/to/target-repo
+kaizen-agentic schedule prepare coach --target /path/to/target-repo
+```
+
+### Session orientation
+
+```bash
+# MCP when available
+get_domain_summary("coulomb_social")
+```
+
+Fallback: `.custodian-brief.md`

.claude/rules/workplan-convention.md

@@ -0,0 +1,17 @@
+## Workplan Convention (ADR-001)
+
+File location: `workplans/LOOP-WP-NNNN-<slug>.md`
+ID prefix: `LOOP-WP` (see `docs/adr/ADR-001-workplan-prefix.md`)
+
+Work items originate as files in this repo **before** being registered in the hub.
+
+Ecosystem todos from supplier or other agents arrive as `[repo:coulomb-loop]` hub tasks.
+
+After workplan file updates:
+
+```bash
+cd ~/state-hub && make fix-consistency REPO=coulomb-loop
+```
+
+Customer loop workplans: LOOP-WP-0000 (bootstrap), LOOP-WP-0001–0004 (loops).
+Supplier mirror: `kaizen-agentic` KAIZEN-WP-0008.