From e0d7b0c3ada0c71cba736f23f2173c997ddcd284 Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 16 Jul 2026 10:28:58 +0200 Subject: [PATCH] docs: forward-deployed agency model, architecture, and WP-0009 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Kai trial-currency business model and engagement architecture (request → bound agent → ramp-up/down, client vault). Register workplan KAIZEN-WP-0009 for host-operator@railiance01 pilot and CLI/ledger phases. --- docs/agency-framework.md | 3 + ...orward-deployed-engagement-architecture.md | 702 ++++++++++++++++++ wiki/ForwardDeployedAgencyBusinessModel.md | 373 ++++++++++ wiki/PricingModel.md | 12 +- wiki/RevenueModel.md | 11 +- ...agentic-WP-0009-forward-deployed-agency.md | 269 +++++++ 6 files changed, 1368 insertions(+), 2 deletions(-) create mode 100644 docs/forward-deployed-engagement-architecture.md create mode 100644 wiki/ForwardDeployedAgencyBusinessModel.md create mode 100644 workplans/kaizen-agentic-WP-0009-forward-deployed-agency.md diff --git a/docs/agency-framework.md b/docs/agency-framework.md index 0e851ad..4a56d26 100644 --- a/docs/agency-framework.md +++ b/docs/agency-framework.md @@ -345,6 +345,9 @@ Schema: [integrations/schedule-schema.md](integrations/schedule-schema.md). - [ADR-003: Protocols Artifact Convention](adr/ADR-003-protocols-artifact-convention.md) - [ADR-004: Project Metrics Convention](adr/ADR-004-project-metrics-convention.md) - [ADR-005: Scheduled Agent Execution](adr/ADR-005-scheduled-agent-execution.md) +- [ADR-006: Customer Engagement Convention](adr/ADR-006-customer-engagement-convention.md) +- [Forward-Deployed Engagement Architecture](forward-deployed-engagement-architecture.md) — client-requestable Roles, ramp-up/down, client vaults +- [wiki/ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md) — Kai trial currency, seats/duties, confidentiality - [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md) — two-layer measurement model - [WP-0002: Agency Framework](../workplans/kaizen-agentic-WP-0002-agency-framework.md) - [WP-0003: Measurement Loop](../workplans/kaizen-agentic-WP-0003-measurement-loop.md) diff --git a/docs/forward-deployed-engagement-architecture.md b/docs/forward-deployed-engagement-architecture.md new file mode 100644 index 0000000..415636b --- /dev/null +++ b/docs/forward-deployed-engagement-architecture.md @@ -0,0 +1,702 @@ +# Forward-Deployed Engagement Architecture + +**Status:** draft specification v0.1 +**Date:** 2026-07-16 +**Type:** architecture extension (not yet an accepted ADR) +**Companion business model:** [wiki/ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md) +**Extends:** ADR-002 (memory), ADR-003 (protocols), ADR-005 (schedule), ADR-006 (customer engagement) + +--- + +## 1. Purpose + +Extend kaizen-agentic from **installing agent personas into repos** to **staffing +forward-deployed agents for client engagements**, with: + +1. A client **request → provision** path that yields a bound **agent definition** +2. Explicit **ramp-up** and **ramp-down** phases +3. **Confidential client knowledge** separated from supplier Role IP +4. Hooks for **Kai trial currency** (and later EUR) settlement events +5. A concrete first engagement: **host-operator for railiance01** (coulomb infra) + +This document is the technical contract. Implementation may land across +`kaizen-agentic`, customer engagement repos, `activity-core`, State Hub, and +access systems (`ops-warden`, OpenBao) without collapsing those ownership lines. + +--- + +## 2. Goals and non-goals + +### Goals + +- Clients can **request** a Role for named Targets and receive a **provisioned engagement** +- Each engagement has machine-readable **lifecycle state** and phase checklists +- Operational knowledge accumulates in a **client-owned vault**, not in the + supplier catalog by default +- Ramp-up produces an **operationally aware** agent; ramp-down produces a + **handoff pack** and access revocation +- Duty sessions can emit **billing events** (Kai) without putting secrets in the ledger +- First pilot maps cleanly onto existing **sys-medic** craft + host ops duties + +### Non-goals (v0.1) + +- Full multi-tenant SaaS control plane +- Autonomous root changes without human gates +- Replacing activity-core, State Hub, or ops-warden +- Public Kai cryptocurrency or payment processor integration +- Guaranteeing 24/7 unattended SRE autonomy + +--- + +## 3. Conceptual model + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Client (company / coulomb project) │ +│ request, fund (Kai), accept handoff, own engagement vault │ +└───────────────┬─────────────────────────────────────────────────┘ + │ EngagementRequest + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Agency control plane (kaizen-agentic + optional hub records) │ +│ Role catalog · Engagement lifecycle · Quote/ledger hooks │ +└───────┬─────────────────────────┬───────────────────────────────┘ + │ bind Role + policies │ schedule / prepare + ▼ ▼ +┌───────────────────┐ ┌─────────────────────────────────────────┐ +│ Agent definition │ │ Execution plane │ +│ (engagement-bound │ │ coding agent / Claude · activity-core │ +│ prompt + policy) │ │ sessions on allowed Targets │ +└─────────┬─────────┘ └──────────────────┬──────────────────────┘ + │ writes │ observes / acts (gated) + ▼ ▼ +┌───────────────────┐ ┌─────────────────────────────────────────┐ +│ Engagement vault │ │ Targets (repos, hosts e.g. railiance01) │ +│ CLIENT OWNED │ │ access via warden certs / approved paths│ +└───────────────────┘ └─────────────────────────────────────────┘ +``` + +### Core entities + +| Entity | Definition | Owner | +|--------|------------|-------| +| **Role** | Versioned supplier product (`host-operator@1.2.0`) — craft + protocols | Supplier | +| **Client** | Organization or coulomb project account | Client | +| **Target** | Thing the agent attends (host, cluster, repo, product area) | Client | +| **Engagement** | Binding of Role × Client × Targets × policy × lifecycle | Shared record; vault is client | +| **Agent definition** | Concrete prompt + frontmatter materialised for an engagement | Generated; stored per policy | +| **Engagement vault** | Memory, profiles, session logs, handoff | **Client** | +| **Duty session** | One execution of the agent under the engagement | Ephemeral | +| **Ledger entry** | Kai charge/credit for seat/duty/access | Settlement system | + +--- + +## 4. Relationship to existing architecture + +| Existing piece | How FDA (forward-deployed agency) uses it | +|----------------|-------------------------------------------| +| `agents/agent-*.md` | **Role templates** (generic craft) | +| `.kaizen/agents//memory.md` | Becomes **vault path** under engagement scope (not only project-root generic) | +| Coach / `memory brief` | **Ramp-up orientation** producer | +| Protocols (`agents/protocols/...`) | Role procedures; engagement may pin versions | +| `.kaizen/schedule.yml` | Duty cadence on target repos / engagement schedule file | +| ADR-006 customer engagement repo | Still holds loop contracts; FDA adds **staffed Role engagements** | +| activity-core | Optional cron fire for scheduled duties | +| ops-warden / OpenBao | Access class enforcement — never invent secrets in agent prompts | +| Metrics (ADR-004) | Quality + billing correlates; no secret payloads | + +**Important distinction:** + +- **coulomb-loop style engagement** = improvement *loop* across a *repo roster* +- **FDA engagement** = *Role staffing* against *Targets* (hosts, systems, teams) + +A client may run both. They share CLI primitives and confidentiality principles +but different primary artifacts (`loops/` vs `engagements/`). + +--- + +## 5. Data model (schemas) + +### 5.1 Role manifest (supplier) + +Path proposal: `roles//ROLE.yaml` (or package data equivalent). + +```yaml +# roles/host-operator/ROLE.yaml +apiVersion: kaizen.agentic/v1 +kind: Role +metadata: + id: host-operator + version: "0.1.0" + title: Host Operator + category: infrastructure + capability_tier: 4 # PricingModel multiplier M +spec: + description: > + Competent technical administrator for named Linux hosts — OS currency, + security posture, load and workload review, operational continuity. + base_agent: sys-medic # craft inheritance + protocols: + - agent: sys-medic + slug: k3s-node-health-assessment + - agent: host-operator + slug: os-security-pass # new protocol for this Role + - agent: host-operator + slug: load-workload-review + memory_template: host-operator # extends sys-medic sections + default_cadence: + health_review: daily + os_security_pass: weekly + load_review: daily + access_classes_allowed: + - read_only + - host_observe + - privileged_ops # always gated + ramp_up: + checklist_ref: roles/host-operator/ramp-up.md + exit_criteria: + - host_baseline_documented + - access_path_verified + - first_health_review_complete + - coach_orientation_filed + ramp_down: + checklist_ref: roles/host-operator/ramp-down.md + exit_criteria: + - handoff_pack_written + - open_threads_triaged + - access_revoked + - vault_export_confirmed + billing: + seat_product: expert_seat_4x + duty_weights: + standard_review: 1.0 + deep_assessment: 1.0 +``` + +### 5.2 Engagement request (client → agency) + +```yaml +# Example: engagements/requests/2026-07-16-railiance01-host-operator.yaml +apiVersion: kaizen.agentic/v1 +kind: EngagementRequest +metadata: + id: engreq-coulomb-railiance01-ho-001 + created: "2026-07-16" +spec: + client: + id: coulomb + domain_slug: railiance # or coulomb_social / custodian as applicable + billing_account: coulomb-ops-kai + role: + id: host-operator + version_constraint: ">=0.1.0 <1.0.0" + targets: + - kind: host + id: railiance01 + inventory_ref: railiance-hosts # where facts live + notes: "k3s production; forgejo/apps workloads" + duty: + health_review: daily + os_security_pass: weekly + load_review: daily + timezone: Europe/Berlin + access: + requested_classes: [host_observe, privileged_ops] + cert_identity_hint: agt # ops-warden; never store private keys here + knowledge: + vault_placement: client_repo # see §6 + confidentiality: client_owned + commercial: + currency: kai + trial: true + quote_requested: true +``` + +### 5.3 Engagement record (lifecycle source of truth) + +```yaml +apiVersion: kaizen.agentic/v1 +kind: Engagement +metadata: + id: eng-coulomb-railiance01-ho-001 + request_id: engreq-coulomb-railiance01-ho-001 + created: "2026-07-16" + updated: "2026-07-16" +status: + phase: requested # see §7 + # requested | quoting | funded | staffing | ramp_up | operating + # renewing | ramp_down | closed | cancelled +spec: + client: { id: coulomb, billing_account: coulomb-ops-kai } + role: { id: host-operator, version: "0.1.0" } + targets: + - kind: host + id: railiance01 + agent_definition: + path: engagements/eng-coulomb-railiance01-ho-001/agent-host-operator.md + derived_from: agents/agent-sys-medic.md + vault: + root: engagements/eng-coulomb-railiance01-ho-001/vault/ + memory: engagements/eng-coulomb-railiance01-ho-001/vault/memory.md + schedule: + path: engagements/eng-coulomb-railiance01-ho-001/schedule.yml + policy: + confidentiality: client_owned + human_approval_for: [privileged_ops, package_upgrade, firewall_change, reboot] + redaction_profile: default-host-ops + commercial: + currency: kai + seat_product: expert_seat_4x + ledger_ref: kai://coulomb-ops-kai/eng-coulomb-railiance01-ho-001 +``` + +### 5.4 Agent definition (engagement-bound) + +Materialised markdown with frontmatter — what the runtime actually loads. + +```yaml +--- +name: host-operator +engagement_id: eng-coulomb-railiance01-ho-001 +role_id: host-operator +role_version: "0.1.0" +description: Host operator for railiance01 (coulomb engagement) +category: infrastructure +memory: enabled +memory_path: engagements/eng-coulomb-railiance01-ho-001/vault/memory.md +targets: + - kind: host + id: railiance01 +confidentiality: client_owned +phase: ramp_up +access_classes: [host_observe, privileged_ops] +human_approval_for: [privileged_ops, package_upgrade, firewall_change, reboot] +model: inherit +--- +``` + +Body = Role prompt (from template) + **engagement binding section** (targets, +escalation contacts, change windows, vault paths, forbidden actions) + phase +protocol includes. + +Supplier catalog keeps the **unbound** Role template. The bound definition may +live in the **client engagement repo** (preferred for confidential bindings). + +--- + +## 6. Knowledge planes and vault layout + +### 6.1 Placement rules + +| Content | Location | Sync to supplier repo? | +|---------|----------|------------------------| +| Role prompt template | `kaizen-agentic/roles/` or `agents/` | N/A (source) | +| Engagement record + bound definition | Client engagement repo (or client-private store) | No (except non-secret metrics summary if opted-in) | +| Memory, node profiles, incident notes | **Engagement vault** (client) | **Never** by default | +| Scrubbed protocol improvement | Supplier PR after client license | Yes, after review | +| Kai ledger lines | Settlement store | Billing metadata only | + +### 6.2 Vault directory (client-owned) + +``` +engagements// +├── ENGAGEMENT.yaml # lifecycle record +├── agent-host-operator.md # bound definition +├── schedule.yml # duty cadence +├── access-plan.md # how certs/routes work (no secrets) +├── vault/ +│ ├── memory.md # extended host-operator memory +│ ├── baselines/ +│ │ └── railiance01.md # OS, packages, known load envelope +│ ├── session-log/ # optional per-session files +│ ├── findings/ # durable finding tickets +│ └── handoff/ # filled during ramp-down +├── reports/ # client-visible session reports +└── commercial/ + └── quote.yaml # Kai quote snapshot +``` + +### 6.3 Memory template extension (host-operator) + +Inherits sys-medic sections and adds: + +```markdown +## Engagement Charter + + +## Host Profiles + + +## OS & Patch State + + +## Security Posture + + +## Load & Workload Envelope + + +## Recurring Findings +## Cleared Issues +## Open Threads +## Session Log +``` + +### 6.4 Redaction gate (supplier craft feedback) + +Before any vault content may influence a public Role update: + +1. Run `kaizen-agentic engagement scrub --to-lesson` +2. Output must pass checklist: no hostnames (or allowlisted), no IPs, no user + names, no secret material, no tenant identifiers +3. Client marker `contribute_lesson: approved` in engagement record +4. Human maintainer merges into Role/protocol + +Without steps 3–4, scrubbed output is discarded. + +--- + +## 7. Lifecycle state machine + +``` +requested → quoting → funded → staffing → ramp_up → operating ⇄ renewing + │ + ↓ + ramp_down → closed + +Any non-terminal state → cancelled (with partial ramp-down if vault exists) +``` + +### 7.1 Phase responsibilities + +#### `requested` +- Client submits `EngagementRequest` +- Agency validates Role exists, Targets well-formed, access classes allowed + +#### `quoting` +- Produce Kai quote (seat + ramp + estimated duties) +- Client accepts or revises scope + +#### `funded` +- Ledger holds seat + ramp-up package (or soft-reserve for internal grants) +- Insufficient Kai → remain in quoting with `funding_blocked` + +#### `staffing` +- Pin Role version +- Materialise bound agent definition +- Create vault scaffold + schedule +- Register optional activity-core definition / hub task links +- Verify access path **without** storing secrets (`warden route`, dry-run SSH, etc.) + +#### `ramp_up` +Mandatory checklist (host-operator): + +| ID | Criterion | Evidence | +|----|-----------|----------| +| RU-01 | Access path verified | access-plan.md + successful observe session | +| RU-02 | Host baseline documented | vault/baselines/railiance01.md | +| RU-03 | Coach / orientation brief filed | vault or reports/orientation.md | +| RU-04 | First health review complete | reports/ + memory session log | +| RU-05 | Security snapshot initial | OS & Security Posture sections non-empty | +| RU-06 | Load envelope initial | Load & Workload Envelope non-empty | +| RU-07 | Escalation contacts confirmed | Engagement Charter | +| RU-08 | Human approval path tested | dry-run privileged proposal logged | + +Exit: all RU-* done → `operating`. Kai: charge ramp-up package on phase entry +or exit (pick one; **recommend charge on entry**, refund if cancelled before RU-01). + +#### `operating` +- Scheduled duties fire (activity-core or manual) +- Each session: load vault → work → update vault → metrics → ledger duty charge +- Privileged actions require human approval record +- Phase may enter `renewing` near seat period end + +#### `ramp_down` +Mandatory checklist: + +| ID | Criterion | Evidence | +|----|-----------|----------| +| RD-01 | Open threads triaged | memory Open Threads resolved or transferred | +| RD-02 | Handoff pack written | vault/handoff/README.md + baselines export | +| RD-03 | Outstanding risks listed | handoff/risks.md | +| RD-04 | Access revoked / certs not renewed | access-plan.md “revoked at …” | +| RD-05 | Schedule disabled | schedule.yml enabled false / activity-core disabled | +| RD-06 | Client confirms vault custody | engagement status note | +| RD-07 | Supplier workspace scrubbed | no client vault copies in kaizen-agentic tree | + +Exit: all RD-* → `closed`. Charge ramp-down package on entry. + +#### `closed` +- Terminal. Ledger finalised. Definition retained only in client custody + (supplier may keep engagement id + non-secret metrics aggregate if opted-in). + +--- + +## 8. Request → provision API / CLI surface + +Proposed CLI (kaizen-agentic), additive and offline-friendly where possible: + +```bash +# Client / operator +kaizen-agentic engagement request --file request.yaml +kaizen-agentic engagement quote +kaizen-agentic engagement fund --account coulomb-ops-kai + +# Agency staffing +kaizen-agentic engagement staff --role host-operator +kaizen-agentic engagement render-agent +kaizen-agentic engagement init-vault + +# Lifecycle +kaizen-agentic engagement phase --to ramp_up +kaizen-agentic engagement checklist +kaizen-agentic engagement phase --to operating +kaizen-agentic engagement prepare # session bundle like schedule prepare +kaizen-agentic engagement close-session --metrics ... --kai-duty standard_review + +# Knowledge boundary +kaizen-agentic engagement scrub --to-lesson +kaizen-agentic engagement export-handoff +kaizen-agentic engagement phase --to ramp_down +kaizen-agentic engagement phase --to closed +``` + +**Session prepare bundle** includes: + +1. Bound agent definition +2. Vault memory + baselines +3. Relevant protocols (pinned) +4. Access plan (no secrets) +5. Phase-specific instructions (ramp-up vs operate vs ramp-down) +6. Commercial context (duty type for ledger) + +This reuses the spirit of `schedule prepare` (ADR-005) with engagement scope. + +### State Hub (optional index) + +Do **not** invent workplans by hand in the hub. Options: + +- Engagement markdown/YAML in client repo + `fix-consistency` if modeled as workplan, **or** +- Lightweight hub records: progress events only (`add_progress_event`) keyed by engagement id in detail JSON + +Prefer **files as source of truth** (ADR-001 spirit). + +--- + +## 9. Access control integration + +Agents never hold long-lived secrets in definitions or vaults. + +| Need | Route | +|------|-------| +| SSH to railiance01 | `warden sign` / cert_command — ops-warden | +| API tokens, DB passwords | OpenBao via `warden route` pointers | +| Tunnel to services | ops-bridge | +| Authorization decisions | flex-auth (if applicable) | + +**Access classes** in the engagement record constrain what the agent may *propose* +and what the prepare bundle states as allowed. Runtime still depends on human +and cert policy; the definition is policy-as-documentation plus checklist gates. + +### Privileged ops gate + +```text +Agent produces Action Proposal + → Engagement policy requires human approval for class + → Human records approval in vault/session-log or hub progress event + → Agent may execute within stated blast radius + → Session close updates Cleared Issues / Findings +``` + +--- + +## 10. Billing event schema (Kai) + +Emitted at duty close and phase transitions (implementation may be JSONL local +ledger first): + +```json +{ + "apiVersion": "kaizen.agentic/v1", + "kind": "KaiLedgerEntry", + "id": "kai-20260716T100000Z-001", + "account": "coulomb-ops-kai", + "engagement_id": "eng-coulomb-railiance01-ho-001", + "type": "duty_charge", + "product": "standard_review", + "capability_tier": 4, + "access_surcharge_product": "host_observe", + "amount_kai": 1700, + "currency": "KAI", + "session_ref": "reports/2026-07-16-health-review.md", + "created_at": "2026-07-16T10:00:00Z", + "metadata": { + "target": "railiance01", + "phase": "operating", + "tokens_vendor_cost_eur": null + } +} +``` + +**Forbidden in ledger:** secrets, full command transcripts with sensitive output, +raw vault dumps. + +Seat charges: `type: seat_charge` on period boundaries. +Ramp packages: `type: ramp_up_charge` / `ramp_down_charge`. + +--- + +## 11. First example: coulomb host-operator on railiance01 + +### 11.1 Context + +- **Client:** coulomb (platform / railiance ops) +- **Target:** host `railiance01` — production k3s node (Forgejo, apps, cluster services per railiance-hosts inventory) +- **Role:** `host-operator` (tier 4), craft base `sys-medic` +- **Duty:** keep system operational and secure; OS up to date; regular review of system load and demanding workloads + +### 11.2 Engagement charter (normative for pilot) + +**In scope** + +- OS package currency and reboot planning (with approval) +- Security hygiene: listeners, basic firewall posture, cert expiry awareness, user/session leftovers +- Load average, CPU, memory, disk, inode pressure +- Workload identification: heavy processes, container/pod resource hogs, backup/jobs overlap +- k3s node health signals (reuse sys-medic protocol where applicable) +- Documentation of baselines and findings in the engagement vault +- Recommendations and gated remediation proposals + +**Out of scope (unless separately engaged)** + +- Application feature development +- Unilateral production data deletion +- Multi-host fleet automation without engagement expansion +- Secret value retrieval into chat or git +- Changing DNS, billing, or legal identity systems + +**Cadence (pilot)** + +| Duty | When | Protocol | +|------|------|----------| +| Health + load review | Daily | load-workload-review + sys-medic assessment subset | +| OS & security pass | Weekly | os-security-pass | +| Deep assessment | On demand / monthly | full sys-medic k3s protocol | +| Incident assist | On demand | privileged gate as needed | + +### 11.3 Suggested inventory anchors (read-only facts) + +- `railiance-hosts` inventory and SCOPE (host list, ops-bridge notes) +- `railiance-apps` / forgejo-on-railiance01 docs for workload expectations +- Existing sys-medic node profile sections if any prior `.kaizen` memory exists on related repos + +### 11.4 Ramp-up sequence (pilot runbook) + +1. Create `EngagementRequest` (YAML above) +2. Quote + fund from `coulomb-ops-kai` (or internal grant) +3. `engagement staff` → render agent + vault under client engagement store +4. Verify observe access to railiance01 (cert path) +5. Capture baseline: uname, uptime, disk, memory, load, top workloads, k3s node status +6. Coach brief (if other agent memories exist on related projects) +7. Complete RU checklist → mark `operating` +8. Enable daily/weekly schedule entries + +### 11.5 Ramp-down sequence + +1. Freeze new duties; finish in-flight session +2. Triage open threads (transfer to humans or new engagement) +3. Write handoff pack: baseline, known risks, deferred patches, “how we operate railiance01” +4. Disable schedules; revoke agent access +5. Confirm vault remains in client custody +6. Scrub supplier working trees +7. Close engagement; finalise Kai ledger + +### 11.6 Mapping to sys-medic today + +Until `host-operator` Role package exists: + +| Need | Temporary approach | +|------|--------------------| +| Agent prompt | Install/use `sys-medic` + engagement binding appendix | +| Memory | Init `.kaizen/agents/sys-medic/` **or** engagement vault path via override | +| Protocols | Existing k3s-node-health-assessment + draft os/load protocols in engagement repo | +| Schedule | Manual or activity-core definition owned by client engagement repo | + +Promotion path: generalize binding appendix into `roles/host-operator/` in +kaizen-agentic once pilot checklist passes twice. + +--- + +## 12. Security & compliance checklist + +- [ ] No secrets in git (engagement YAML, agent definition, vault baselines) +- [ ] Vault encryption at rest if hosted on shared infra (client policy) +- [ ] Session transcripts: client retention policy; default not uploaded to supplier +- [ ] Privileged actions require recorded approval +- [ ] Redaction gate before any Role craft PR +- [ ] Access via short-lived certs; no password in prompts +- [ ] Ledger free of sensitive operational detail +- [ ] Ramp-down access revocation verified + +--- + +## 13. Implementation phases + +### Phase 0 — Spec only (this document + business model) +- Accept as working draft; no code required + +### Phase 1 — File-based pilot (minimal code) +- Directory convention under a client engagement repo +- Manual phase transitions in ENGAGEMENT.yaml +- sys-medic + appendix as bound definition +- JSONL Kai ledger in `commercial/ledger.jsonl` +- Checklists as markdown + +### Phase 2 — CLI scaffolding +- `engagement` command group (request, staff, render-agent, checklist, prepare, scrub) +- Validate schemas +- Integrate `memory brief` / metrics record with vault paths + +### Phase 3 — Orchestration +- activity-core definitions per engagement schedule +- Optional State Hub progress events +- Ledger → quote reporting + +### Phase 4 — Commercial EUR path +- FX export from Kai history +- Hybrid billing metadata + +--- + +## 14. Acceptance criteria (architecture) + +1. A client can express an **EngagementRequest** for host-operator @ railiance01 +2. Staffing produces a **bound agent definition** + **client vault** + **schedule** +3. Ramp-up and ramp-down have **testable exit criteria** +4. Operating sessions **update client vault**, not supplier `agents/` by default +5. Each duty can append a **Kai ledger entry** without secrets +6. Pilot runbook in §11 is executable by an operator in one working day for Phase 1 + +--- + +## 15. Open technical questions + +1. Single monorepo path `engagements/` vs dedicated client engagement repo per company? + (**Recommend:** dedicated client repo or subdirectory in existing ops repo — e.g. railiance-hosts or a new `coulomb-ops-engagements`.) +2. Should bound definitions be signed (supply-chain) for production host ops? +3. Multi-target engagements: one agent definition vs. one per host? + (**Recommend:** one engagement, N targets, N baseline files.) +4. How aggressively to share metrics aggregates with supplier optimizer by default? + (**Recommend:** off until opt-in flag on engagement.) + +--- + +## Related documents + +- [wiki/ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md) +- [agency-framework.md](agency-framework.md) +- [adr/ADR-006-customer-engagement-convention.md](adr/ADR-006-customer-engagement-convention.md) +- [adr/ADR-005-scheduled-agent-execution.md](adr/ADR-005-scheduled-agent-execution.md) +- [adr/ADR-002-project-memory-convention.md](adr/ADR-002-project-memory-convention.md) +- [integrations/customer-engagement-playbook.md](integrations/customer-engagement-playbook.md) +- [agents/agent-sys-medic.md](../agents/agent-sys-medic.md) diff --git a/wiki/ForwardDeployedAgencyBusinessModel.md b/wiki/ForwardDeployedAgencyBusinessModel.md new file mode 100644 index 0000000..4ab0ec4 --- /dev/null +++ b/wiki/ForwardDeployedAgencyBusinessModel.md @@ -0,0 +1,373 @@ +# Forward-Deployed Agency Business Model + +**Status:** draft v0.1 +**Date:** 2026-07-16 +**Audience:** product owners, coulomb ecosystem operators, early client sponsors +**Companion tech spec:** [docs/forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md) +**Builds on:** [PricingModel.md](PricingModel.md), [RevenueModel.md](RevenueModel.md), [KaizenAgenticMission.md](KaizenAgenticMission.md), ADR-006 + +--- + +## 1. Positioning + +**Kaizen-agentic is an agentic consulting practice** — a digital talent agency that +**forward-deploys specialized agents** into client environments (companies on the +coulomb ecosystem, and coulomb-operated infrastructure itself). + +Unlike a library of one-shot prompts, engagements are **staffed roles**: + +| Dimension | Meaning | +|-----------|---------| +| **Role competency** | The agent is good at its job (sysadmin, coach, TDD lead, release manager) | +| **Domain competency** | The agent learns *this* client's systems, jargon, constraints, and history | +| **Confidential custody** | Operational knowledge gained on engagement **belongs to the client** | +| **Reusable craft** | Role patterns, playbooks, and non-secret refinements improve the agency fleet | + +Clients do not rent anonymous token burn. They engage a **named digital colleague** +with a ramp-up, steady-state duty, and orderly ramp-down — analogous to a +forward-deployed engineer, with measurement and continuous improvement baked in. + +### Who is the customer? + +1. **Coulomb internal** — ecosystem ops (e.g. railiance01 host operator, loop coaches) +2. **Coulomb-ecosystem companies** — product teams using railiance, state-hub, activity-core, etc. +3. **Later: external companies** — same model once trial currency proves unit economics + +--- + +## 2. Value proposition + +### For the client + +- A competent agent **on their problem**, not a generic chatbot +- Knowledge that **stays in their custody** (engagement vault; see tech spec) +- Explicit lifecycle: request → staff → ramp-up → operate → ramp-down → handoff +- Transparent cost model that starts in trial currency and can convert to money +- Measurable duty: schedules, health reviews, SLAs stated in the engagement contract + +### For the agency (kaizen-agentic) + +- Recurring engagement revenue (or trial-currency demand signal) beyond one-off installs +- Dual learning loops: + - **Role craft** compounds in supplier IP (prompts, protocols, coach patterns) + - **Domain craft** compounds only where the client allows (engagement memory) +- Reference deployments inside coulomb that prove the model before external sales +- Natural upsell path: more roles, higher cadence, premium tiers (capability multipliers) + +### What is *not* sold + +- Client secrets, host fingerprints, incident narratives, or tenant topology as + kaizen training data +- Unbounded autonomous change rights on production systems +- Transfer of client operational IP into the public agent catalog without scrubbing + and explicit license + +--- + +## 3. Engagement product units + +### 3.1 Role (catalog product) + +A **Role** is a supplier-owned agent definition family (e.g. `host-operator`, +`sys-medic`, `coach`, `tdd-workflow`). Roles have: + +- Capability tier (1×–5× per [PricingModel.md](PricingModel.md)) +- Standard protocols and metrics +- Default cadences (on-demand, daily, weekly) +- Required access classes (read-only shell, cert-bound SSH, no secrets, etc.) + +### 3.2 Engagement (sold instance) + +An **Engagement** is a time-bounded (or open-ended) staffing of one or more Roles +for a **Client** against named **Targets** (repos, hosts, clusters, product areas). + +| Field | Example (pilot) | +|-------|-----------------| +| Client | coulomb / railiance ops | +| Role | `host-operator` (specialization of infrastructure / sys-medic craft) | +| Target | host `railiance01` (k3s production node) | +| Duty | keep OS current, security posture, load & workload review | +| Cadence | daily health review; weekly OS/security pass; on-demand incident assist | +| Knowledge plane | client-owned engagement vault on client infrastructure | +| Billing plane | trial Kai ledger → later EUR settlement | + +### 3.3 Seat vs. duty + +- **Seat** — right to run a role for a client (subscription-like) +- **Duty unit** — a scheduled or on-demand work session (usage-like) + +Pricing can combine both (seat for continuity + duty units for heavy weeks). + +--- + +## 4. Dual knowledge planes (commercial rule) + +This is the commercial expression of the technical confidentiality design. + +| Plane | Owner | Contents | May feed supplier IP? | +|-------|-------|----------|------------------------| +| **Client operational knowledge** | Client | Host baselines, incident history, topology, credentials pointers, “how we run X here” | **No** — unless client explicitly contributes a scrubbed lesson | +| **Role craft (agency IP)** | kaizen-agentic | Prompts, protocols, assessment methods, generic playbooks | Yes — always | +| **Shared anonymized metrics** | Negotiated | Aggregate success rates, quality scores, cadence stats | Opt-in only | +| **Engagement artifacts** | Client | Session reports, run logs, recommendations | Client; supplier may retain *billing* metadata only | + +**Default contract language:** *“All operational knowledge acquired during the +engagement is Client Confidential Information. Supplier retains ownership of +generic Role definitions and non-identifying process improvements.”* + +Violation of this plane split is a product defect, not a negotiation detail. + +--- + +## 5. In-game currency: **Kai** + +### 5.1 Purpose + +**Kai** is a **trial and internal settlement unit** used while the agency model is +proven inside coulomb and with friendly clients. It: + +- Creates real scarcity and budget discipline without invoicing friction +- Makes role tiers and duty costs *felt* before EUR conversion +- Produces ledger data to calibrate real prices +- Can later map 1:1 (or with a published FX) to currency + +Kai is **not** a cryptocurrency, not publicly traded, and not legal tender. +It is a **ledger balance** in the coulomb / kaizen settlement system. + +### 5.2 Units and denominations + +| Symbol | Name | Typical use | +|--------|------|-------------| +| **Kai** | base unit | All ledger entries | +| **kKai** | 1 000 Kai | Monthly seat packages | +| **MKai** | 1 000 000 Kai | Portfolio budgets (optional) | + +### 5.3 Minting (trial phase) + +| Source | Amount (illustrative) | Notes | +|--------|----------------------|--------| +| **Bootstrap grant** | 50 000 Kai per new client | One-time, expires in 90 days if unused | +| **Internal coulomb ops grant** | 200 000 Kai / quarter | Ecosystem self-service (railiance, loop, etc.) | +| **Top-up voucher** | Operator-issued | For pilots and demos | +| **Earned credit** | Variable | Completing engagement feedback, contributing scrubbed lessons | + +No automatic infinite mint. Empty balance **pauses new duty starts** (ramp-down of +in-flight work is always allowed without charge). + +### 5.4 Spend catalog (trial price list) + +Prices are in Kai and intentionally round for mental math. Capability multipliers +from [PricingModel.md](PricingModel.md) apply as **tier weights** on duty units. + +**Seats (monthly, auto-renew while funded):** + +| Product | Tier weight | Seat / month | +|---------|-------------|--------------| +| Baseline role seat (1×) | 1 | 2 000 Kai | +| Professional role seat (3×) | 3 | 6 000 Kai | +| Expert / host-operator seat (4×) | 4 | 10 000 Kai | +| Premium meta / coach fleet seat (5×) | 5 | 15 000 Kai | + +**Duty units (per executed session, in addition to seat):** + +| Duty | Base cost | After tier weight *M* | +|------|-----------|------------------------| +| On-demand short assist (≤30 min wall) | 100 Kai | 100 × *M* | +| Standard review session (scheduled) | 400 Kai | 400 × *M* | +| Deep assessment / change window | 1 200 Kai | 1 200 × *M* | +| Ramp-up package (fixed, once) | 5 000 Kai | 5 000 × *M* / 2 (half weight) | +| Ramp-down package (fixed, once) | 3 000 Kai | 3 000 × *M* / 2 | + +**Access class surcharges (per session):** + +| Access class | Surcharge | +|--------------|-----------| +| Read-only / docs-only | +0 | +| Host observe (non-root shell / metrics) | +100 Kai | +| Privileged ops (root, package upgrade, firewall) | +400 Kai + human approval gate | +| Multi-host or cluster-wide | +200 Kai per additional host | + +**LLM token pass-through (optional, trial):** +Recorded as `token_kai = ceil(actual_vendor_cost_EUR * kai_per_eur_fx)` for +transparency; may be waived in pure internal coulomb trials. + +### 5.5 Example: railiance01 host-operator pilot + +| Line item | Calc | Kai | +|-----------|------|------| +| Expert seat (4×), 1 month | 10 000 | 10 000 | +| Ramp-up package | 5 000 × 4 / 2 | 10 000 | +| Daily standard review × 20 business days | 20 × 400 × 4 | 32 000 | +| Weekly deep OS/security pass × 4 | 4 × 1 200 × 4 | 19 200 | +| Privileged surcharges (est. 4 sessions) | 4 × 400 | 1 600 | +| **Month-1 total** | | **~72 800 Kai** | + +Internal coulomb quarterly grant (200 000 Kai) covers ~2–3 such seats with +headroom — enough to run the pilot and still force prioritization. + +### 5.6 Conversion to real payments + +When trial ends (client or product decision), **Kai balances convert**: + +``` +EUR_due = remaining_committed_work_EUR + + (optional) unused_Kai_forfeit or credit_at_FX +``` + +**Published FX (initial, revisable):** + +| Mode | Rule | +|------|------| +| **Trial learning FX** | 1 000 Kai ≈ 1 EUR of agency list price *for calibration only* | +| **Commercial FX** | Seat and duty price lists republished in EUR; Kai ledger frozen or becomes loyalty credit | +| **Grandfathering** | Active engagements keep trial Kai rates for one more full billing cycle after conversion notice | + +**Transition states:** + +1. `trial_kai` — only Kai ledger +2. `hybrid` — seats invoiced in EUR; duty still in Kai (or reverse) +3. `commercial_eur` — full EUR; Kai optional loyalty only + +Settlement systems (invoice, SEPA, etc.) are **out of repo**; this model only +defines the commercial units and conversion rules. + +### 5.7 What Kai deliberately does *not* buy + +- Secrets or elevated access without ops-warden / OpenBao routing +- Guaranteed zero-incident outcomes +- Ownership of supplier Role IP +- Training the public catalog on client confidential data + +--- + +## 6. Competency model (what improves over time) + +### 6.1 Role competency (agency asset) + +Improved via: + +- Metrics (success, quality, time) across *many* engagements +- Coach + optimizer loops (existing agency framework) +- Protocol runbooks refined after generalized lessons +- Capability tier promotion of Role products + +**Commercial effect:** higher tier weight → higher Kai/EUR price, justified by +lower client risk and better outcomes. + +### 6.2 Domain competency (client asset) + +Improved via: + +- Engagement memory and node/host profiles +- Client runbooks and decisions in the engagement vault +- Session logs and cleared-issue history + +**Commercial effect:** longer engagements get more efficient (fewer duty units for +the same outcome). Discounts for multi-quarter renewals reflect reduced ramp cost, +not ownership transfer of client knowledge. + +### 6.3 Learning tax and learning credit + +| Event | Effect | +|-------|--------| +| First engagement of a new Role for a client | Ramp-up package mandatory | +| Client contributes scrubbed “lesson learned” accepted into Role craft | Kai credit (e.g. 1 000–5 000) | +| Supplier extracts confidential detail into public Role without approval | Contract breach; engagement freeze | + +--- + +## 7. Lifecycle commercial view + +``` +Request → Quote (Kai) → Fund → Staff → Ramp-up → Operate → (Renew | Ramp-down) → Close +``` + +| Phase | Client pays | Client receives | Agency obligation | +|-------|-------------|-----------------|-------------------| +| **Request / quote** | 0 | Scope options, tier recommendation | Respond with Role fit + Kai estimate | +| **Staff** | Seat (pro-rate) | Named engagement + agent definition bound to targets | Provision definition + access plan | +| **Ramp-up** | Ramp package | Orientation, baselines, coach brief, first metrics | Achieve “operationally aware” exit criteria | +| **Operate** | Seat + duty | Scheduled work, reports, continuous memory | Meet cadence & safety policy | +| **Renew** | Next seat period | Continuity; optional tier change | No re-ramp if knowledge vault intact | +| **Ramp-down** | Ramp-down package | Handoff pack, knowledge export, revoke access | Clean exit; no residual client secrets at supplier | +| **Close** | Settlement | Final ledger + EUR conversion if any | Archive billing metadata only | + +--- + +## 8. Go-to-market inside coulomb + +### Phase A — Internal dogfood (now) + +- Clients: coulomb projects and railiance ops +- Currency: Kai only +- First Role: **host-operator** on **railiance01** +- Success: 30 days of reviews, OS/security pass documented, load findings actionable + +### Phase B — Ecosystem companies + +- Same Kai ledger; bootstrap grants +- Roles: host-operator, coach/optimizer loop, release manager, TDD +- Playbook reuse from coulomb-loop (ADR-006) + this model + +### Phase C — External commercial + +- EUR price list derived from Kai consumption data +- Hybrid then commercial_eur +- Optional professional services (custom Role design) as separate line items + (see [RevenueModel.md](RevenueModel.md) §4) + +--- + +## 9. Relationship to existing pricing docs + +| Document | Role after this model | +|----------|----------------------| +| [PricingModel.md](PricingModel.md) | **Capability multipliers** remain the tier engine (*M*) | +| [RevenueModel.md](RevenueModel.md) | **Margin story** for EUR phase; Kai is pre-revenue instrumentation | +| This document | **Engagement packaging**, confidential knowledge, trial currency, lifecycle | + +Token markup formula `Price = C × M` still applies when vendor tokens are +pass-through. Engagement pricing adds **seat + duty + access class** so that +value is not *only* token volume (a careful weekly review can be high value with +modest tokens). + +--- + +## 10. Risks and mitigations + +| Risk | Mitigation | +|------|------------| +| Kai inflation (infinite grants) | Quarterly mint caps; empty balance pauses duty | +| Client confuses trial with free forever | Expiry on grants; conversion notice period | +| Knowledge leak into public agents | Dual planes; automated redaction gates (tech spec); legal default | +| Over-autonomous privileged ops | Access class + human approval; safety-first Role principles | +| Underpriced expert seats | Recalibrate FX after 2–3 pilots using actual duty mix | +| Scope creep on “operator” Role | Engagement contract lists hosts, cadences, change windows | + +--- + +## 11. Success metrics (business) + +1. **Pilot completion** — railiance01 host-operator engagement runs full lifecycle once +2. **Ledger fidelity** — ≥95% of duty sessions post a Kai charge event +3. **Knowledge boundary audit** — zero confidential client artifacts in supplier `agents/` without scrub + license +4. **Renewal signal** — client chooses renew or ramp-down with documented handoff +5. **Price calibration** — published EUR draft list within ±30% of Kai-implied spend after conversion FX + +--- + +## 12. Open decisions (for sponsor) + +1. Who operates the Kai ledger (state-hub extension vs. lightweight YAML ledger vs. finance tool)? +2. Is internal coulomb billed only in Kai forever, or eventually soft EUR for cost visibility? +3. Multi-tenant companies: one client account or one per product line? +4. Can unused Kai transfer between sister projects in the same company? + +--- + +## Related + +- Technical architecture: [docs/forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md) +- Customer engagement convention: [ADR-006](../docs/adr/ADR-006-customer-engagement-convention.md) +- Agency framework: [docs/agency-framework.md](../docs/agency-framework.md) +- Mission: [KaizenAgenticMission.md](KaizenAgenticMission.md) diff --git a/wiki/PricingModel.md b/wiki/PricingModel.md index d76641c..53ed72d 100644 --- a/wiki/PricingModel.md +++ b/wiki/PricingModel.md @@ -60,6 +60,16 @@ On top of token-based billing, KaizenAgentic can introduce **subscription layers * **Predictable:** Clients can forecast spend by capability tier, independent of vendor-specific LLM pricing changes. * **Flexible:** Basemodel transparent to avoid basemodel lockin supporting various providers (ChatGPT, Claude, Cursor, etc.). +--- -xxx +### 6. Engagement packaging (forward-deployed agency) +Capability multipliers (*M*) remain the tier engine for Role products. For +**staffed engagements** (seats, duty sessions, ramp-up/down, trial currency **Kai**, +and conversion to EUR), see: + +* [ForwardDeployedAgencyBusinessModel.md](ForwardDeployedAgencyBusinessModel.md) +* Technical companion: [docs/forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md) + +Token formula `C × M` still applies when vendor tokens are pass-through; engagement +pricing adds seat + duty + access-class so value is not only token volume. diff --git a/wiki/RevenueModel.md b/wiki/RevenueModel.md index 4294c33..fabc5f1 100644 --- a/wiki/RevenueModel.md +++ b/wiki/RevenueModel.md @@ -75,5 +75,14 @@ Assume: 👉 This makes KaizenAgentic operate like a **“talent agency margin model”**: you pay the “raw salary” (token cost to the model vendor), and KaizenAgentic earns its cut (markup × value of coaching/optimization). +--- -xxx +### 7. Forward-deployed engagements and trial currency + +Staffed Roles (host-operator, coach fleet, etc.) add **seat + duty** revenue on top +of token markup. Trial phase settles in **Kai** (in-game ledger) to calibrate prices +before EUR invoicing. Confidential client operational knowledge is **not** a +supplier data asset — only scrubbed, licensed lessons may improve Role craft. + +See [ForwardDeployedAgencyBusinessModel.md](ForwardDeployedAgencyBusinessModel.md) +and [docs/forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md). diff --git a/workplans/kaizen-agentic-WP-0009-forward-deployed-agency.md b/workplans/kaizen-agentic-WP-0009-forward-deployed-agency.md new file mode 100644 index 0000000..818f4cc --- /dev/null +++ b/workplans/kaizen-agentic-WP-0009-forward-deployed-agency.md @@ -0,0 +1,269 @@ +--- +id: KAIZEN-WP-0009 +type: workplan +title: "Forward-deployed agency: engagements, Kai ledger, host-operator pilot" +domain: agents +repo: kaizen-agentic +status: ready +owner: kaizen-agentic +topic_slug: custodian +created: "2026-07-16" +updated: "2026-07-16" +depends_on: + - KAIZEN-WP-0002 + - KAIZEN-WP-0006 + - KAIZEN-WP-0008 +tasks: + - id: T01 + status: done + title: Business model and architecture drafts (Kai + engagement lifecycle) + - id: T02 + status: todo + title: Accept or revise open decisions; promote drafts to accepted reference + - id: T03 + status: todo + title: Role package scaffold for host-operator (ROLE.yaml + protocols) + - id: T04 + status: todo + title: Phase 1 file-based engagement layout and pilot ENGAGEMENT for railiance01 + - id: T05 + status: todo + title: Bound agent definition from sys-medic craft + engagement binding appendix + - id: T06 + status: todo + title: Ramp-up and ramp-down checklists with exit criteria evidence paths + - id: T07 + status: todo + title: JSONL Kai ledger convention and quote snapshot for pilot + - id: T08 + status: todo + title: CLI engagement command group (request, staff, prepare, checklist, scrub) + - id: T09 + status: todo + title: Wire prepare/session-close to vault paths, metrics, and ledger entries + - id: T10 + status: todo + title: Run railiance01 host-operator Phase 1 pilot through ramp-up exit + - id: T11 + status: todo + title: Absorb pilot friction; ADR for engagement convention; docs cross-links +--- + +# KAIZEN-WP-0009 — Forward-Deployed Agency + +**Status:** ready +**Owner:** kaizen-agentic +**Repo:** kaizen-agentic +**Depends on:** WP-0002 (agency memory), WP-0006 (schedule prepare), WP-0008 (customer engagement) + +## Goal + +Turn kaizen-agentic into an **agentic consulting / forward-deployed agency** capability: +clients (coulomb ecosystem companies and coulomb ops itself) can **request a Role**, +receive a **bound agent definition**, run engagements with **ramp-up / operate / +ramp-down**, keep **operational knowledge client-confidential**, and settle trial +costs in **Kai** (transitionable to EUR later). + +First concrete pilot: **host-operator** Role attending **railiance01** (OS currency, +security posture, load and workload review). + +## Background + +Specs already drafted: + +| Doc | Purpose | +|-----|---------| +| [wiki/ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md) | Seats, duties, Kai, confidentiality, conversion | +| [docs/forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md) | Lifecycle, schemas, vault, CLI, pilot runbook | + +Existing building blocks: agency memory (ADR-002), protocols (ADR-003), schedule +prepare (ADR-005), customer engagement convention (ADR-006), `sys-medic` craft. + +## Engagement model (supplier view) + +``` +Client request → quote (Kai) → fund → staff Role → ramp-up → operate → ramp-down + │ + ├─ bound agent definition (client engagement store) + ├─ engagement vault (CLIENT OWNED) + └─ ledger entries (billing metadata only) +``` + +## Tasks + +## Business model and architecture drafts + +```task +id: KAIZEN-WP-0009-T01 +status: done +priority: high +``` + +Delivered 2026-07-16: + +- `wiki/ForwardDeployedAgencyBusinessModel.md` +- `docs/forward-deployed-engagement-architecture.md` +- Cross-links from PricingModel, RevenueModel, agency-framework + +## Accept open decisions + +```task +id: KAIZEN-WP-0009-T02 +status: todo +priority: high +``` + +Resolve architecture open questions with sponsor: + +1. Kai ledger home (file JSONL vs hub extension) +2. Engagement store placement (dedicated repo vs railiance-hosts subdirectory) +3. Multi-target agent binding shape +4. Default metrics opt-in for supplier optimizer + +Update both draft docs to `accepted` / v0.2 when decided. Optionally promote +architecture sections into ADR-007. + +## host-operator Role package + +```task +id: KAIZEN-WP-0009-T03 +status: todo +priority: high +``` + +Add supplier Role scaffold per architecture §5.1: + +- `roles/host-operator/ROLE.yaml` (or agreed package path) +- Protocols: `os-security-pass`, `load-workload-review` (plus reuse sys-medic k3s) +- Memory template extensions (host profiles, OS/patch, security, load envelope) +- Capability tier 4; base_agent: sys-medic + +## Phase 1 engagement layout + pilot record + +```task +id: KAIZEN-WP-0009-T04 +status: todo +priority: high +``` + +Create file-based engagement tree for pilot (location per T02 decision), including: + +- `ENGAGEMENT.yaml` for `eng-coulomb-railiance01-ho-001` +- Request YAML, schedule.yml, access-plan.md (no secrets) +- Empty vault scaffold + +Document the path in architecture §11 if it differs from the draft proposal. + +## Bound agent definition + +```task +id: KAIZEN-WP-0009-T05 +status: todo +priority: high +``` + +Materialise engagement-bound agent definition from sys-medic + binding appendix +(targets, phase, human_approval_for, vault paths, charter). Until Role package +ships, sys-medic + appendix is acceptable; migrate to host-operator when T03 lands. + +## Ramp checklists + +```task +id: KAIZEN-WP-0009-T06 +status: todo +priority: medium +``` + +Author ramp-up (RU-01…RU-08) and ramp-down (RD-01…RD-07) checklists with +evidence paths matching architecture §7. Link from ENGAGEMENT.yaml. + +## Kai ledger (Phase 1) + +```task +id: KAIZEN-WP-0009-T07 +status: todo +priority: medium +``` + +- `commercial/ledger.jsonl` schema per architecture §10 +- Quote snapshot for pilot month-1 seat + ramp + estimated duties +- Document mint/spend against internal coulomb grant (no real EUR required) + +## CLI engagement group + +```task +id: KAIZEN-WP-0009-T08 +status: todo +priority: medium +``` + +Implement `kaizen-agentic engagement` subcommands (Phase 2 of architecture): + +`request`, `quote`, `staff`, `render-agent`, `init-vault`, `phase`, `checklist`, +`prepare`, `scrub`, `export-handoff` — minimum viable subset for pilot may be +`staff`, `checklist`, `prepare`, `phase`. + +Tests for schema validate and checklist status. + +## Session wire-up + +```task +id: KAIZEN-WP-0009-T09 +status: todo +priority: medium +``` + +- `engagement prepare` bundles definition + vault + protocols + access plan +- Session close path updates vault, `metrics record`, optional Kai duty charge +- No secrets in prepare output or ledger + +## railiance01 pilot through ramp-up + +```task +id: KAIZEN-WP-0009-T10 +status: todo +priority: high +``` + +Execute architecture §11 ramp-up runbook against railiance01 (observe-class +access via warden/cert paths). Exit when RU checklist complete and phase +`operating`. Privileged changes only with recorded human approval. + +Evidence: baseline file, first health report, checklist marks, ledger entries. + +## Absorb and ADR + +```task +id: KAIZEN-WP-0009-T11 +status: todo +priority: low +``` + +- Supplier notes → playbook / architecture v0.2 +- ADR-007 (or equivalent) for engagement convention if T02 promotes it +- CHANGELOG + wiki links; optional activity-core schedule for daily review + +## Out of scope + +- EUR payment processor / invoicing systems +- Autonomous root without human gates +- Replacing ops-warden, OpenBao, activity-core, or State Hub +- Public Kai cryptocurrency +- Fleet-wide host-operator rollout beyond railiance01 pilot + +## Success criteria + +1. Specs accepted (T02) and committed as team reference +2. Pilot engagement files exist with bound definition and client vault +3. Ramp-up exit criteria met once on railiance01 with evidence +4. Kai ledger records seat/ramp/duty without confidential payloads +5. No client vault content merged into supplier `agents/` without scrub + license +6. CLI or documented manual procedure can re-run prepare/checklist + +## Related + +- [ForwardDeployedAgencyBusinessModel.md](../wiki/ForwardDeployedAgencyBusinessModel.md) +- [forward-deployed-engagement-architecture.md](../docs/forward-deployed-engagement-architecture.md) +- [ADR-006](../docs/adr/ADR-006-customer-engagement-convention.md) +- [agent-sys-medic.md](../agents/agent-sys-medic.md) +- [KAIZEN-WP-0008](kaizen-agentic-WP-0008-coulomb-loop-supplier-engagement.md)