183 lines
7.1 KiB
Markdown
183 lines
7.1 KiB
Markdown
# 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`; 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)
|
|
|
|
```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; 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)
|
|
|
|
```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 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](../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/)
|