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 / ADR-006).

Canon: ADR-007 Reference pilot: engagements/pilots/eng-coulomb-railiance01-ho-001/ Business model: 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

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)

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:

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

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

5. Ramp-up

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)

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; they declare intent but do not activate unattended work by themselves
• Continue manual prepare until an engagement-specific activity-core definition and versioned Glas execution profile have passed a bounded smoke test
• Daily: health + load; weekly: OS/security pass (privileged changes still gated)

8. Ramp-down (when ending)

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; target railiance-infra for Railiance01 and require receiver acceptance before source cleanup
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)

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
• Pilot table + quick commands: engagement access-plan.md

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 unattended wiring (Phase 3)

Not required for operate. When ready:

1. Customer or engagement repo owns the ActivityDefinition that identifies the engagement and emits idempotent, claimable ops_run work in activity-core.
2. The run or bound agent instance carries organizational references and an approved versioned harness_profile_ref; it does not carry secrets or raw provider prompts.
3. Rein-local intake or another caller claims/receives the work and constructs the Glas ExecutionRequest. Glas resolves the concrete rein, model, sandbox, tool policy, and limits; the selected rein executes kaizen-agentic engagement prepare <id> inside the bounded session.
4. Completion links the ops_run, engagement report, metrics, and State Hub progress without duplicating confidential content into coordination records.
5. Keep privilege gates in the agent definition regardless of schedule fire.

---

Related

• ADR-007
• forward-deployed-engagement-architecture.md
• customer-engagement-playbook.md (loops)
• CLI_CHEAT_SHEET.md — engagement section
• Role: roles/host-operator