kaizen-agentic/docs/integrations/forward-deployed-engagement-playbook.md

# Forward-Deployed Engagement Playbook v1 (supplier)

How to staff a **Role** for a client Target (host, cluster, product area) with
ramp-up / operate / ramp-down. Complements the **loop** playbook
([customer-engagement-playbook.md](customer-engagement-playbook.md) / ADR-006).

**Canon:** [ADR-007](../adr/ADR-007-forward-deployed-engagement-convention.md)
**Reference pilot:** `engagements/pilots/eng-coulomb-railiance01-ho-001/`
**Business model:** [wiki/ForwardDeployedAgencyBusinessModel.md](../../wiki/ForwardDeployedAgencyBusinessModel.md)

---

## When to use this playbook

| Situation | Use |
|-----------|-----|
| Client needs a named digital colleague on a duty (e.g. host operator) | **This playbook** |
| Client wants repo fleet coach/optimizer cadence | ADR-006 loop playbook |
| Both | Both trees; do not mix vaults |

---

## Bootstrap checklist (staffed Role)

### 1. Role package exists (supplier)

```
roles/<role-id>/ROLE.yaml
roles/<role-id>/agent-definition.md
roles/<role-id>/protocols/...
roles/<role-id>/ramp-up.md
roles/<role-id>/ramp-down.md
```

If missing: author Role from craft base (e.g. host-operator from sys-medic).

### 2. Staff engagement

```bash
kaizen-agentic engagement staff \
  --id eng-<client>-<target>-<role-short> \
  --role <role-id> \
  --client <client-id> \
  --target <target-id>
kaizen-agentic engagement validate eng-...
```

Or copy the pilot tree and edit `ENGAGEMENT.yaml`.

### 3. Fund / quote (Kai trial)

```bash
kaizen-agentic engagement quote eng-...
# fill commercial/quote.yaml; ledger starts empty or with quote_open note
```

### 4. Access plan (no secrets)

Document SSH alias, user, identity path, bridge tunnels, and verify:

```bash
ssh -o BatchMode=yes <host-alias> 'hostname; uptime'
```

Update `access-plan.md` verification log → mark **RU-01**.

### 5. Ramp-up

```bash
kaizen-agentic engagement phase eng-... --to ramp_up
kaizen-agentic engagement prepare eng-... > /tmp/prepare.md
# run observe session; write baseline + health report
kaizen-agentic engagement checklist eng-... --mark RU-02=done
# ... until RU complete
kaizen-agentic engagement phase eng-... --to operating
```

### 6. Session close (each duty)

```bash
kaizen-agentic engagement close-session eng-... \
  --success --duty standard_review \
  --summary "<one-line non-secret outcome>" \
  --time <s> --quality <0-1> \
  --access-class host_observe
```

### 7. Operate cadence

- Enable entries in engagement `schedule.yml` (manual prepare until activity-core)
- Daily: health + load; weekly: OS/security pass (privileged changes still gated)

### 8. Ramp-down (when ending)

```bash
kaizen-agentic engagement phase eng-... --to ramp_down
kaizen-agentic engagement export-handoff eng-...
# complete RD checklist; revoke access; phase closed
kaizen-agentic engagement phase eng-... --to closed
```

---

## Supplier notes — railiance01 host-operator pilot (absorbed 2026-07-16)

Friction and resolutions from `eng-coulomb-railiance01-ho-001` / KAIZEN-WP-0009.

| Observation | Resolution / guidance |
|-------------|----------------------|
| ADR-006 loop layout does not fit host staffing | ADR-007 + this playbook; separate `engagements/` tree |
| Open decisions blocked scaffolding | DEC-FDA-001 → elevated into ADR-007 |
| Forgejo git push intermittent (publickey / pre-receive) | Retry; keep commits local; hub task status can PATCH via API |
| SSH to forgejo `git@` failed; shell SSH as tegwick worked | Document **both** paths; access-plan records what actually works |
| warden inventory sparse vs bridge “connected” | Bridge may use static keys; do not block observe on warden cert status alone |
| Undersized host (2 core / 3.8G / no swap) for full stack | First duty may exit ramp-up with **Critical** health — still valid ramp-up if RU evidence complete |
| `k3s kubectl` ServiceUnavailable under memory pressure | Record as finding; avoid hammering API; re-sample after capacity relief |
| Nested `.kaizen/metrics` under engagement is correct for custody | Root `.gitignore` `.kaizen/metrics/` only ignores repo-root metrics; pilot metrics are commit-able |
| Privileged work tempting on Critical host | RU-08 = **proposal dry-run only** until human approval table filled |
| Pilot vault in supplier repo | Treat as client confidential; export to client ops repo before multi-tenant scale |
| activity-core not required for Phase 1 | Manual `prepare` + `close-session`; schedule.yml documents intent |
| Kai charges felt real only after close-session | Always close-session after live duties; quote alone is not spend |
| High load makes remote `du`/`apt` slow | Prefer short command batches; timeout ≥60s for full assessments |

### Reference commands (pilot)

```bash
kaizen-agentic engagement show eng-coulomb-railiance01-ho-001
kaizen-agentic engagement prepare eng-coulomb-railiance01-ho-001
ssh railiance01 'free -h; uptime; cat /proc/pressure/memory'
kaizen-agentic engagement close-session eng-coulomb-railiance01-ho-001 \
  --success --duty standard_review --summary "..." --time 120 --quality 0.8
```

### UFW k3s API admin allowlist

After remediation, port **6443** is allowlist-only. Procedure:

- Role protocol: [`roles/host-operator/protocols/ufw-admin-allowlist.md`](../../roles/host-operator/protocols/ufw-admin-allowlist.md)
- Pilot table + quick commands: engagement `access-plan.md`

```bash
curl -4 -s ifconfig.me; echo   # on admin laptop
ssh railiance01 "sudo ufw allow from <PUBLIC_IP> to any port 6443 proto tcp comment 'k3s-api-admin-<label>'"
```

### Open human decisions from pilot (not supplier code)

1. Add RAM and/or temporary swap on railiance01
2. journald vacuum approval
3. Security package upgrade window
4. UFW source restriction for 6443/8472

---

## Optional activity-core wiring (Phase 3)

Not required for operate. When ready:

1. Customer or engagement repo owns ActivityDefinition copies that shell out to
   `kaizen-agentic engagement prepare <id>` then start a coding-agent session
2. Resolver points at engagement id / host Target (new work — not WP-0009)
3. Keep privilege gates in the agent definition regardless of cron fire

---

## Related

- [ADR-007](../adr/ADR-007-forward-deployed-engagement-convention.md)
- [forward-deployed-engagement-architecture.md](../forward-deployed-engagement-architecture.md)
- [customer-engagement-playbook.md](customer-engagement-playbook.md) (loops)
- [CLI_CHEAT_SHEET.md](../CLI_CHEAT_SHEET.md) — `engagement` section
- Role: [roles/host-operator](../../roles/host-operator/)