kaizen-agentic/docs/INTEGRATION_PATTERNS.md

Integration Patterns

How kaizen-agentic composes with ecosystem repos by contract — no merged codebases, no duplicated capabilities.

Reference: wiki/EcosystemIntegration.md, KAIZEN-WP-0004.

---

Pattern 1 — Helix Forge correlation (agentic-resources)

Problem: Project metrics and fleet session metrics answer different questions.

Contract: Optional helix_session_uid on ADR-004 execution records.

kaizen-agentic	agentic-resources
metrics record at session close	Helix capture → digest store
metrics correlate <uid> read-only lookup	Store.get_digest(session_uid)
HELIX_SESSION_UID env auto-merge	Session.session_uid

Docs: integrations/helix-forge-correlation.md

Boundary: kaizen-agentic does not ingest session JSONL.

---

Pattern 2 — activity-core triggers

Problem: Recurring kaizen checks need scheduling without custom cron in this repo.

Contract: ActivityDefinition markdown files declare triggers + actions that invoke kaizen-agentic CLI commands.

Definition	Trigger	CLI command
weekly-metrics-optimize	Cron Mon 08:00	metrics optimize
post-install-metrics-scaffold	kaizen.agent.installed	memory init validation
low-success-rate-review	kaizen.metrics.recorded	metrics record --emit-event

Activation handoff (activity-core owners):

1. Copy definitions from kaizen-agentic: docs/integrations/activity-definitions/*.md → activity-core activity-definitions/kaizen-agentic/ (or org-equivalent path per ACT-ADR-002).
2. Register in activity-core index — ensure each definition slug appears in the activity-core catalog consumed by the resolver.
3. Run sync in activity-core: make sync-activity-definitions (or repo-equivalent).
4. Wire triggers — map cron / NATS subjects (kaizen.agent.installed, kaizen.metrics.recorded) to the documented CLI invocations.
5. Enable gradually — set enabled: true per definition after a manual smoke test against a repo with .kaizen/metrics/ populated.
6. Verify credentials — scheduled runs need kaizen-agentic on PATH and any Forgejo PyPI extra index if the runner installs from registry (see PACKAGE_RELEASE.md).

kaizen-agentic maintainer checklist:

• Three definition files committed under docs/integrations/activity-definitions/
• activity-core handoff completed for the resolver and pilot definitions
• Smoke test commands documented below passed on the pilot roster

Smoke test (manual):

# Against a repo with populated metrics
cd /path/to/project-with-kaizen
kaizen-agentic metrics list
kaizen-agentic metrics optimize
# Verify analysis.json written
test -f .kaizen/metrics/optimizer/analysis.json && echo OK

Boundary: kaizen-agentic does not run Temporal schedules or own durable work.

Scheduled agent execution (WP-0006, ADR-005)

Beyond the metrics-only definitions above, agents themselves run on a cadence against a preselected repo roster. The roster combines three sources:

Source	Purpose
State Hub GET /repos/	Canonical slug list + host_paths
Repo opt-in: .kaizen/schedule.yml exists with version set	Per-repo enablement
Optional hub flag kaizen_schedule_enabled: true (future)	Operator override

A repo is schedule-eligible when it is registered with reachable host_paths and carries a valid .kaizen/schedule.yml. The activity-core resolver discover_kaizen_scheduled_repos intersects these and emits context.scheduled_runs (one entry per (repo, agent)); definitions for_each over that output.

Definition	Trigger	Agent	Prepare command
weekly-coach-orientation	Cron Mon 09:00	coach	schedule prepare coach
weekly-optimization-review	Cron Mon 10:00	optimization	schedule prepare optimization

Listing schedule-eligible repos (operator, no activity-core code):

# In each candidate repo on a host listed in state-hub host_paths:
kaizen-agentic schedule validate && kaizen-agentic schedule list

Design docs (no state-hub / activity-core code in this repo):

• schedule-schema.md — .kaizen/schedule.yml
• state-hub-roster-fields.md — hub fields/filters
• discover-kaizen-scheduled-repos.md — resolver spec
• kaizen-schedule-prepared-event.md — event payload

Current automated runtime

The original WP-0006 resolver and manual prepare smoke established the supplier contract. Current unattended execution composes it as follows:

Stage	Owner	Contract
Schedule/event and eligibility	activity-core	Temporal definition/rule plus repo/agent context
Durable work	activity-core	Unique idempotency key, ops_run state, lease, retry, result
Claim and execution	rein-aharness	Claim loop, agent-session approach, policy/profile/runtime resolution
Agent orientation	kaizen-agentic	schedule prepare <agent> offline bundle
Coordination evidence	State Hub	Roster, workplan/progress references; never prompts or secrets
Improvement evidence	kaizen-agentic / artifact-store	Project metrics and optional durable artifacts

Manual invocation remains supported for smoke tests and operator-controlled work. The automated path should keep prompts, secrets, and raw model output out of ops_run and State Hub records.

Boundary: kaizen-agentic declares and prepares; activity-core schedules and queues; rein-aharness executes; State Hub owns the roster and coordination view.

---

Pattern 3 — artifact-store evidence retention

Problem: Optimizer outputs need durable, attributable retention beyond local disk.

Contract: metrics publish registers analysis.json + recommendations.jsonl as an artifact package with retention_class: raw-evidence.

export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<token>
kaizen-agentic metrics optimize
kaizen-agentic metrics publish --target .

Manifest: integrations/optimizer-artifact-manifest.md

Boundary: Publish is optional; local .kaizen/metrics/optimizer/ remains canonical.

---

Pattern 4 — Canon and knowledge (stretch)

Design-only paths for info-tech-canon and kontextual-engine:

• integrations/canon-template-mapping.md
• integrations/briefs/tdd-workflow-canon-brief.md
• integrations/kontextual-wiki-ingestion-spike.md

No runtime dependency in WP-0004.

---

Environment variables

Variable	Used by	Purpose
HELIX_SESSION_UID	metrics record	Fleet session correlation
HELIX_REPO, HELIX_FLAVOR	metrics record	Session context
HELIX_TOKENS, HELIX_INFRA_OVERHEAD_SHARE	metrics record	Fleet cost fields
HELIX_STORE_DB	metrics correlate	Digest lookup database
ARTIFACTSTORE_API_URL	metrics publish	Registry endpoint
ARTIFACTSTORE_API_TOKEN	metrics publish	Write auth bearer token