Files

tegwick b48a2102d7 WP-0004: ecosystem integration complete

Add Helix Forge correlation (HELIX_SESSION_UID env, metrics correlate),
artifact-store publish (metrics publish), activity-core ActivityDefinition
references, integration patterns docs, and canon/knowledge design artifacts.

2026-06-16 01:53:01 +02:00

6.8 KiB

Raw Blame History

Ecosystem Integration

How KaizenAgentic composes with adjacent repositories

KaizenAgentic (INTENT.md) defines a meta-improvement layer for coding agents. No single repository implements the full vision. This document describes the two-layer measurement model and integration contracts with ecosystem repos.

Two-Layer Measurement Model

Layer	Question answered	Owner	Storage
Project	How is this agent persona performing in this repo?	kaizen-agentic	`.kaizen/metrics/<agent>/`
Fleet	How are coding sessions performing across repos?	agentic-resources	Helix Forge digest store + baselines

  Coding session (Claude / Codex / Grok)
           │
           ├──────────────────────────────────────┐
           ▼                                      ▼
  agentic-resources                      kaizen-agentic
  (Helix Forge)                          (session close)
  Capture → Digest → Fleet metrics     metrics record → executions.jsonl
           │                                      │
           └──────── helix_session_uid ───────────┘
                         (optional link)

When to use which layer

Project metrics — optimizer recommendations, Coach briefs, per-agent kaizen loop in one codebase (ADR-004).
Fleet metrics — cross-repo friction analysis, pattern distribution, weekly retro, tooling decisions (Helix Forge PRD).

Kaizen-agentic does not re-implement session JSONL ingestion. It may cite Helix session UIDs on project execution records for correlation.

Integration Partners

agentic-resources (P0)

Helix Forge — session capture, fleet aggregates, baselines, weekly retro.

KaizenAgentic	Helix Forge
`.kaizen/metrics/<agent>/executions.jsonl`	Digest store + `measure/baselines.jsonl`
Per-agent persona outcomes	Per-session cross-repo outcomes
`kaizen-agentic metrics optimize`	`session_memory/measure/` aggregates

Correlation fields (ADR-004): helix_session_uid, repo, flavor, tokens, infra_overhead_share.

Workplan: KAIZEN-WP-0004 Part 1.

Worked example

A TDD8 session captured by Helix Forge and closed with kaizen metrics:

# Helix capture sets (or operator exports) session identity
export HELIX_SESSION_UID="claude:17092961-abc"
export HELIX_REPO="kaizen-agentic"
export HELIX_FLAVOR="claude"
export HELIX_TOKENS="12500"

# Session close — project layer
kaizen-agentic metrics record tdd-workflow --success --time 4200 --quality 0.92

# Inspect project record (includes correlation fields)
kaizen-agentic metrics show tdd-workflow

# Fleet lookup — read-only, no ingestion in kaizen-agentic
export HELIX_STORE_DB=~/.helix-forge/store.db
kaizen-agentic metrics correlate claude:17092961-abc

Project executions.jsonl carries helix_session_uid for audit; fleet analytics remain in agentic-resources digest store. Coach memory brief surfaces project ## Performance Summary; correlate adds fleet context when needed.

Contract: docs/integrations/helix-forge-correlation.md.

activity-core (P1)

Event bridge — scheduled and event-driven task creation.

ActivityDefinition reference copies (sync into activity-core to activate):

Workplan: KAIZEN-WP-0004 Part 2. Patterns: docs/INTEGRATION_PATTERNS.md.

artifact-store (P1)

Evidence retention — durable registry for generated outputs.

optimizer/analysis.json
recommendations.jsonl snapshots
E2e pilot evidence packages

Retention class: raw-evidence (180d default, aligned with ADR-004).

kaizen-agentic metrics optimize
kaizen-agentic metrics publish   # requires ARTIFACTSTORE_API_URL + TOKEN

Manifest: docs/integrations/optimizer-artifact-manifest.md.

Workplan: KAIZEN-WP-0004 Part 3.

info-tech-canon (P2)

Semantic canon — agent briefs, patterns, profiles, validation.

Map KaizenAgentTemplate.md → InfoTechCanon profile format
Publish compact agent briefs per persona
Extend kaizen-agentic validate with canon conformance checks

Workplan: KAIZEN-WP-0004 Part 4.

phase-memory (P2, future)

Memory graphs — upgrade from flat memory.md to phased memory profiles.

Fluid memory → project session paths
Stabilized memory → accumulated findings with provenance
Context packages for Coach brief compilation

No WP-0003 blocker; plan after ecosystem integration baseline.

kontextual-engine (P2)

Knowledge operations — ingest wiki/ and agent definitions as governed assets; runtime for KaizenGuidance catalog when built.

llm-connect (P3)

LLM abstraction — use when Coach/optimizer synthesis becomes automated beyond CLI context assembly. Token metrics align with wiki pricing tiers.

domain-tree (P3)

identity-canon (P3)

Terminology for agent persona vs deployed instance vs session actor — supports "digital talent agency" framing without overloading "user".

tele-mcp (TBD)

Listed on Forgejo; not cloned locally. Candidate telemetry MCP adapter for WP-0001 T04. Assess before depending on it.

Boundary Rules

kaizen-agentic owns agent definitions, .kaizen/ conventions, CLI, Coach/optimizer personas, and product framing (INTENT.md, wiki/).
kaizen-agentic does not own session transcript ingestion, task scheduling, artifact bytes, knowledge graph runtime, or LLM providers.
Integrate by contract — ADRs, shared correlation fields, ActivityDefinitions, artifact registration APIs — not by merging repos.
Evidence compounds — fleet baselines inform tooling; project metrics inform agent specs; artifact-store preserves both for audit.

Reading Order

INTENT.md — purpose and boundaries
wiki/EcosystemIntegration.md — this document
docs/adr/ADR-004-project-metrics-convention.md — project metrics schema
history/2026-06-16-ecosystem-assessment.md — full repo comparison
workplans/kaizen-agentic-WP-0004-ecosystem-integration.md — implementation plan

Persisted in history/:

2026-06-16-intent-gap-analysis.md
2026-06-16-ecosystem-assessment.md

6.8 KiB Raw Blame History