tegwick
b48a2102d7
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.
105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
# Integration Patterns
|
|
|
|
How kaizen-agentic composes with ecosystem repos **by contract** — no merged
|
|
codebases, no duplicated capabilities.
|
|
|
|
Reference: [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md),
|
|
[KAIZEN-WP-0004](../workplans/kaizen-agentic-WP-0004-ecosystem-integration.md).
|
|
|
|
---
|
|
|
|
## 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](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](integrations/activity-definitions/weekly-metrics-optimize.md) | Cron Mon 08:00 | `metrics optimize` |
|
|
| [post-install-metrics-scaffold](integrations/activity-definitions/post-install-metrics-scaffold.md) | `kaizen.agent.installed` | `memory init` validation |
|
|
| [low-success-rate-review](integrations/activity-definitions/low-success-rate-review.md) | `kaizen.metrics.recorded` | `metrics show` + `optimize` |
|
|
|
|
**Activation:**
|
|
|
|
1. Copy or symlink definitions from `docs/integrations/activity-definitions/` into
|
|
activity-core's `activity-definitions/` tree (or register as external ConfigMap).
|
|
2. Run `make sync-activity-definitions` in activity-core.
|
|
3. Enable definitions (`enabled: true`) after resolver wiring is verified.
|
|
|
|
**Smoke test (manual):**
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
---
|
|
|
|
## 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`.
|
|
|
|
```bash
|
|
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](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/canon-template-mapping.md)
|
|
- [integrations/briefs/tdd-workflow-canon-brief.md](integrations/briefs/tdd-workflow-canon-brief.md)
|
|
- [integrations/kontextual-wiki-ingestion-spike.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 | |