# 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:

```bash
# 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](../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):

- [weekly-metrics-optimize](../docs/integrations/activity-definitions/weekly-metrics-optimize.md)
- [post-install-metrics-scaffold](../docs/integrations/activity-definitions/post-install-metrics-scaffold.md)
- [low-success-rate-review](../docs/integrations/activity-definitions/low-success-rate-review.md)

**Workplan:** KAIZEN-WP-0004 Part 2. Patterns: [docs/INTEGRATION_PATTERNS.md](../docs/INTEGRATION_PATTERNS.md).

### artifact-store (P1)

**Evidence retention** — durable registry for generated outputs.

Register after optimizer runs:

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

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

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

Manifest: [docs/integrations/optimizer-artifact-manifest.md](../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)

Register kaizen-agentic and agent categories with primary/secondary domain
bindings when capability catalog matures.

### 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

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

---

## Reading Order

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

---

## Related Assessments

Persisted in `history/`:

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