coulomb/kaizen-agentic
2
0
Fork 0
Code Issues 4 Pull Requests Actions Projects Releases Wiki Activity
Files
3b2edd4a9ef6741fad5553b54d7dd900cd4d514e
kaizen-agentic/docs/INTEGRATION_PATTERNS.md
tegwick 3b2edd4a9e feat: scheduled agent execution via activity-core (WP-0006, v1.3.0) 
Enable kaizen agents to run on a regular cadence against a preselected repo
roster, orchestrated by activity-core and prepared by kaizen-agentic — without
this repo owning cron, Temporal workers, or an LLM runtime.

CLI + module:
- src/kaizen_agentic/schedule.py — .kaizen/schedule.yml parse/validate/scaffold
- `kaizen-agentic schedule` group: init, validate, list, prepare <agent>
  (prepare bundles agent prompt + memory + metrics + repo pointers, offline)
- tests/test_schedule_cli.py — 15 tests

Contract & design:
- ADR-005 scheduled agent execution; schema doc + example manifest
- discover_kaizen_scheduled_repos resolver spec, state-hub roster fields,
  kaizen.schedule.prepared event payload, activity-core handoff checklist
- INTEGRATION_PATTERNS Pattern 2 extended with roster model

ActivityDefinition drafts (enabled: false):
- weekly-coach-orientation, weekly-optimization-review

Docs: agency-framework, CLI cheat sheet, PACKAGE_RELEASE runner prereqs,
EcosystemIntegration, CHANGELOG, TODO. Workplan closed (status: done).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-17 08:19:51 +02:00

159 lines
6.7 KiB
Markdown
Raw Blame History

# 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 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
Gitea 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 PR or issue opened to register definitions
- [ ] Smoke test commands documented below pass on a pilot repo
**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.
### 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](integrations/activity-definitions/weekly-coach-orientation.md) | Cron Mon 09:00 | `coach` | `schedule prepare coach` |
| [weekly-optimization-review](integrations/activity-definitions/weekly-optimization-review.md) | Cron Mon 10:00 | `optimization` | `schedule prepare optimization` |
**Listing schedule-eligible repos** (operator, no activity-core code):
```bash
# 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](integrations/schedule-schema.md) — `.kaizen/schedule.yml`
- [state-hub-roster-fields.md](integrations/state-hub-roster-fields.md) — hub fields/filters
- [discover-kaizen-scheduled-repos.md](integrations/discover-kaizen-scheduled-repos.md) — resolver spec
- [kaizen-schedule-prepared-event.md](integrations/kaizen-schedule-prepared-event.md) — event payload
**Boundary:** kaizen-agentic declares and prepares; activity-core schedules;
state-hub owns the roster.
---
## 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 |
Reference in New Issue View Git Blame Copy Permalink