coulomb/kaizen-agentic
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kaizen-agentic/docs/adr/ADR-007-forward-deployed-engagement-convention.md
tegwick 11fa383817
All checks were successful
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Successful in 2s
Details
ci / test (push) Successful in 2m10s
Details
docs: align execution handoff with Glas
2026-08-21 08:30:13 +02:00

6 KiB
Raw Blame History

ADR-007: Forward-Deployed Engagement Convention

Status: accepted Date: 2026-07-16 Deciders: kaizen-agentic maintainers (supplier) Workplan: KAIZEN-WP-0009 Supersedes for staffing model: none (complements ADR-006) Prior working defaults: DEC-FDA-001

Context

kaizen-agentic evolved from installing coding personas into repos into an agentic consulting / forward-deployed agency: clients request a Role, receive a bound agent definition, and run engagements with ramp-up / operate / ramp-down while keeping operational knowledge client-confidential.

ADR-006 covers improvement-loop customer repos (rosters, activity-core cadence). It does not define:

  • Role product packages
  • Engagement lifecycle and checklists
  • Client vault custody vs supplier craft
  • Trial currency (Kai) settlement files
  • Host/operator-style Targets (not only git repos)

The railiance01 host-operator pilot (KAIZEN-WP-0009) proved a file-based Phase 1 path. We lock the convention so the next engagement does not re-invent structure.

Decision

1. Two engagement kinds (both valid)

Kind Primary artifact ADR
Loop engagement Customer loop repo + fleet .kaizen/schedule.yml ADR-006
Staffed Role engagement engagements/ tree + bound agent + vault this ADR

A client may run both. They share CLI primitives, confidentiality principles, and metrics habits, but different primary trees.

2. Ownership planes

Plane Owner Contents
Role package Supplier (roles/<role-id>/) Prompt craft, protocols, ramp checklists, billing hints
Engagement record + bound definition Client custody (pilot may live under supplier engagements/pilots/ until exported) Targets, phase, policy, schedule
Engagement vault Client confidential Memory, baselines, findings, handoff
Kai ledger Settlement (Phase 1: file JSONL under engagement) Billing metadata only — no secrets
Scrubbed lessons Supplier only after client contribute_lesson: approved Role craft improvements

3. Filesystem layout (Phase 1)

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

engagements/pilots/<engagement-id>/   # or client-owned path later
  ENGAGEMENT.yaml
  agent-*.md
  access-plan.md
  schedule.yml
  request.yaml
  checklists/
  vault/
  reports/
  commercial/

4. Lifecycle phases

requested → quoting → funded → staffing → ramp_up → operating ⇄ renewing
                                              → ramp_down → closed

Illegal transitions require --force (CLI). Ramp-up and ramp-down have checklist exit criteria (RU-, RD-).

5. CLI surface

kaizen-agentic engagement list|show|validate|checklist|phase|prepare|staff
kaizen-agentic engagement close-session|quote|scrub|export-handoff
  • prepare — offline session bundle (no LLM invoke)
  • close-session — vault log + engagement-scoped metrics + Kai ledger + report
  • scrub — heuristic gate before any lesson contribution

6. Access and privilege

  • Credential routing remains ops-warden / OpenBao / ops-bridge (never invent secrets)
  • Observe-class work may proceed with verified SSH
  • privileged_ops, package_upgrade, firewall_change, reboot require recorded human approval in the vault before execution
  • Dry-run privileged proposals satisfy ramp-up “approval path tested” (RU-08)

7. Metrics placement for staffed engagements

Metrics for a staffed Role duty are stored under the engagement tree (.kaizen/metrics/<role>/) so they travel with client vault custody, not the supplier monorepo’s global project metrics by default.

8. Kai trial currency

Phase 1 settles in Kai (file ledger). Seat/duty catalog and FX conversion rules live in the business model wiki. Empty balance pauses new duties; ramp-down always allowed.

9. Relation to DEC-FDA-001

DEC-FDA-001 working defaults are elevated into this ADR. Future overrides should amend this ADR (or a successor), not re-open DEC-FDA-001 silently.

Consequences

Positive

  • Second staffed engagement can copy roles/ + engagement staff + RU/RD checklists
  • Confidentiality boundary is structural, not only policy text
  • Pilot railiance01 is the reference implementation path

Negative / trade-offs

  • Pilot vault currently sits in the supplier repo (engagements/pilots/) under transitional custody. The Railiance01 receiving authority is railiance-infra; transfer requires explicit receiver acceptance before the supplier copy is removed or reduced to a pointer.
  • Manual preparation remains supported. Unattended host duties require an engagement-specific activity-core definition and an approved versioned Glas harness_profile_ref in addition to the generic ops_run intake path.
  • Kai is not a payment processor; EUR path remains future work

Follow-ups

  • Complete the proposed pilot transfer to the client-owned railiance-infra evidence path and record its accepted commit
  • Register engagement-specific activity-core definitions and a Glas execution profile reference for daily host-operator preparation when unattended operation is desired
  • EUR commercial FX after 2–3 engagement calibration cycles

Pilot evidence

  • Engagement: engagements/pilots/eng-coulomb-railiance01-ho-001/
  • Role: roles/host-operator/
  • Workplan: KAIZEN-WP-0009 (T01–T11)
  • Live ramp-up: 2026-07-16 (phase operating; Critical memory/load findings)

Related