coulomb/kaizen-agentic
2
0
Fork 0
Code Issues 4 Pull Requests Actions 1 Projects Releases Wiki Activity

WP-0004: ecosystem integration complete

Browse Source 
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.
This commit is contained in:
Bernd Worsch
2026-06-16 01:53:01 +02:00
parent 4a9c2d9bea
commit b48a2102d7
22 changed files with 1451 additions and 408 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/CLI_CHEAT_SHEET.md
View File

@@ -64,6 +64,16 @@ kaizen-agentic metrics export tdd-workflow
kaizen-agentic metrics optimize tdd-workflow # analyze one agent (≥10 records)
kaizen-agentic metrics optimize # analyze all agents with metrics
# Helix Forge correlation (fleet layer — agentic-resources)
export HELIX_SESSION_UID="claude:<native-id>"
kaizen-agentic metrics record tdd-workflow --success --time 120 --quality 0.9
kaizen-agentic metrics correlate claude:<native-id> # needs HELIX_STORE_DB
# Publish optimizer evidence to artifact-store (optional)
export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<token>
kaizen-agentic metrics publish
# Scaffold memory + metrics together
kaizen-agentic memory init tdd-workflow
kaizen-agentic memory init tdd-workflow --no-metrics # memory only

456
docs/INTEGRATION_PATTERNS.md
View File

@@ -1,401 +1,105 @@
# Integration Patterns for Existing Projects
# Integration Patterns
This guide documents proven patterns for integrating Kaizen Agentic agents into existing projects that already have agent systems.
How kaizen-agentic composes with ecosystem repos **by contract** — no merged
codebases, no duplicated capabilities.
## Overview
Reference: [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md),
[KAIZEN-WP-0004](../workplans/kaizen-agentic-WP-0004-ecosystem-integration.md).
When introducing Kaizen agents to existing projects, you'll encounter various scenarios that require different integration approaches. This guide provides tested patterns and strategies.
---
## Integration Scenarios
## Pattern 1 — Helix Forge correlation (agentic-resources)
### Scenario 1: Clean Integration (No Existing Agents)
**Problem:** Project metrics and fleet session metrics answer different questions.
**When to use**: Project has no existing agent systems.
**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):**
**Pattern**: Direct installation
```bash
kaizen-agentic init . --agents keepaTodofile,keepaChangelog,tdd-workflow
# 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
```
**Benefits**:
- Straightforward setup
- No conflicts to resolve
- Full Kaizen agent functionality
**Boundary:** kaizen-agentic does not run Temporal schedules.
### Scenario 2: Claude Code Integration
---
**When to use**: Project already uses Claude Code with CLAUDE.md.
## 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`.
**Pattern**: Respectful coexistence
```bash
# 1. Detect existing setup
kaizen-agentic detect
# 2. Install compatible agents
kaizen-agentic install keepaTodofile keepaChangelog
# 3. Update CLAUDE.md with new agent references
export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<token>
kaizen-agentic metrics optimize
kaizen-agentic metrics publish --target .
```
**Considerations**:
- Preserve existing CLAUDE.md content
- Add Kaizen agent references to existing documentation
- Maintain Claude Code workflow compatibility
**Manifest:** [integrations/optimizer-artifact-manifest.md](integrations/optimizer-artifact-manifest.md)
### Scenario 3: Custom Agent Replacement
**Boundary:** Publish is optional; local `.kaizen/metrics/optimizer/` remains canonical.
**When to use**: Project has custom agents that overlap with Kaizen functionality.
---
**Pattern**: Gradual migration with backup
```bash
# 1. Analyze existing agents
kaizen-agentic detect --detailed
## Pattern 4 — Canon and knowledge (stretch)
# 2. Create migration plan
kaizen-agentic migrate --dry-run
Design-only paths for info-tech-canon and kontextual-engine:
# 3. Execute migration with backup
kaizen-agentic migrate
```
- [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)
**Steps**:
1. **Backup** existing agents
2. **Map** custom agents to Kaizen equivalents
3. **Migrate** functionality to extensions
4. **Test** new agent workflow
5. **Archive** old agents after verification
No runtime dependency in WP-0004.
### Scenario 4: Hybrid Coexistence
---
**When to use**: Project has essential custom agents that cannot be replaced.
## Environment variables
**Pattern**: Namespace separation
```bash
# 1. Install Kaizen agents in parallel
kaizen-agentic install keepaTodofile --target agents/kaizen/
# 2. Keep custom agents in separate directory
# agents/custom/todo_manager.py
# agents/kaizen/agent-keepaTodofile.md
# 3. Create integration extensions
kaizen-agentic extensions create custom-integration keepaTodofile
```
**Directory Structure**:
```
project/
├── agents/
│ ├── custom/ # Existing custom agents
│ │ ├── todo_manager.py
│ │ └── code_reviewer.py
│ └── kaizen/ # Kaizen agents
│ ├── agent-keepaTodofile.md
│ └── agent-code-refactoring.md
├── .kaizen/
│ └── extensions/ # Integration extensions
└── CLAUDE.md # Updated configuration
```
### Scenario 5: Extension-Based Integration
**When to use**: Custom agents have unique functionality that should be preserved.
**Pattern**: Extend Kaizen agents with custom functionality
```bash
# 1. Create project-specific extension
kaizen-agentic extensions create project-todo keepaTodofile \
--description "TODO manager with custom workflow integration"
# 2. Configure custom behavior
# Edit .kaizen/extensions/project-todo/extension.yml
# 3. Migrate custom logic to extension
```
**Extension Configuration Example**:
```yaml
name: project-todo
base_agent: keepaTodofile
extension_type: functional_extension
description: "TODO manager with custom workflow integration"
configuration:
custom_instructions: |
Follow our project-specific TODO format:
- Use JIRA ticket references
- Include priority levels (P0-P3)
- Auto-assign based on component
custom_commands:
create-epic: "Create epic-level TODO items"
sync-jira: "Synchronize with JIRA tickets"
priority-report: "Generate priority-based reports"
environment_overrides:
JIRA_URL: "https://company.atlassian.net"
TODO_FORMAT: "custom"
```
## Conflict Resolution Patterns
### Name Conflicts
**Problem**: Multiple agents with the same name.
**Pattern**: Rename with suffix
```bash
# Automatic resolution
todo_manager -> todo_manager_custom
keepaTodofile -> keepaTodofile (Kaizen agent)
```
**Implementation**:
- Add `_custom` suffix to project-specific agents
- Update references in scripts and documentation
- Create aliases for backward compatibility
### Functional Overlaps
**Problem**: Multiple agents perform similar functions.
**Pattern**: Choose primary, extend secondary
```bash
# Primary: Kaizen agent (standardized)
# Secondary: Custom agent -> extension
# Example: Both have TODO management
# Decision: Use keepaTodofile as primary
# Convert custom logic to extension
```
**Decision Matrix**:
| Factor | Choose Kaizen | Choose Custom | Create Extension |
|--------|---------------|---------------|------------------|
| Standard functionality | ✅ | ❌ | ✅ |
| Custom business logic | ❌ | ✅ | ✅ |
| Maintenance burden | ✅ | ❌ | ⚠️ |
| Team familiarity | ⚠️ | ✅ | ✅ |
### Integration Order
**Pattern**: Infrastructure first, features last
1. **Infrastructure agents** (setupRepository, tooling-optimization)
2. **Core functionality** (keepaTodofile, keepaChangelog)
3. **Development process** (tdd-workflow, code-refactoring)
4. **Specialized features** (testing-efficiency, datamodel-optimization)
## Project Structure Respect Patterns
### Existing Directory Structures
**Pattern**: Adaptive installation
```bash
# Respect existing structure
project/
├── tools/agents/ # Existing agent directory
├── scripts/ # Existing automation
└── docs/ # Existing documentation
# Kaizen adaptation
kaizen-agentic install --target tools/agents/ keepaTodofile
# Creates: tools/agents/agent-keepaTodofile.md
```
### Configuration File Integration
**Pattern**: Merge, don't replace
```bash
# Before
CLAUDE.md # Existing Claude config
project-config.yml # Existing project config
# After (merged)
CLAUDE.md # Updated with Kaizen agents
project-config.yml # Preserved
.kaizen/extensions.yml # New Kaizen-specific config
```
### Build System Integration
**Pattern**: Extend existing targets
```makefile
# Existing Makefile
test:
pytest tests/
# After Kaizen integration (extended)
test: test-core test-agents
@echo "All tests completed"
test-core:
pytest tests/
test-agents:
kaizen-agentic validate
# New Kaizen targets
agents-status:
kaizen-agentic status
agents-update:
kaizen-agentic update
```
## Safe Transition Strategies
### Phased Rollout
**Phase 1: Detection and Planning**
```bash
# Week 1: Analysis
kaizen-agentic detect --detailed
kaizen-agentic migrate --dry-run
# Decision point: Continue or modify approach
```
**Phase 2: Infrastructure Agents**
```bash
# Week 2: Core infrastructure
kaizen-agentic install setupRepository
# Test and validate before proceeding
```
**Phase 3: Core Functionality**
```bash
# Week 3: Essential agents
kaizen-agentic install keepaTodofile keepaChangelog
# Create extensions for custom functionality
```
**Phase 4: Advanced Features**
```bash
# Week 4: Specialized agents
kaizen-agentic install tdd-workflow code-refactoring
# Full integration testing
```
### Rollback Strategy
**Pattern**: Versioned backups with restore capability
```bash
# Before migration
.kaizen-migration-backup-timestamp/
├── agents/ # Original agents
├── CLAUDE.md # Original configuration
└── restoration.md # Rollback instructions
# Rollback command (if needed)
kaizen-agentic rollback --backup .kaizen-migration-backup-timestamp/
```
### Validation Gates
**Pattern**: Automated validation at each phase
```bash
# After each phase
kaizen-agentic validate
make test
make agents-status
# Success criteria for proceeding:
# ✅ All agents load without errors
# ✅ All tests pass
# ✅ No functionality regressions
```
## Best Practices
### Communication
1. **Team Notification**: Inform team before starting migration
2. **Documentation**: Update project docs with new agent workflows
3. **Training**: Provide team training on Kaizen agents
4. **Gradual Adoption**: Allow team to adapt gradually
### Technical
1. **Backup Everything**: Create comprehensive backups
2. **Test Thoroughly**: Validate each integration step
3. **Monitor Impact**: Watch for performance or workflow impacts
4. **Version Control**: Commit changes in logical phases
### Maintenance
1. **Regular Updates**: Keep Kaizen agents updated
2. **Extension Maintenance**: Maintain custom extensions
3. **Documentation Sync**: Keep docs synchronized with agent changes
4. **Team Feedback**: Collect and act on team feedback
## Troubleshooting Common Issues
### Agent Conflicts
**Issue**: Multiple agents trying to manage the same files.
**Solution**:
```bash
# Identify conflicts
kaizen-agentic detect --detailed
# Resolve with namespace separation
mkdir agents/legacy agents/kaizen
mv agents/todo_manager.py agents/legacy/
kaizen-agentic install --target agents/kaizen/ keepaTodofile
```
### Configuration Conflicts
**Issue**: Conflicting configuration files.
**Solution**:
```bash
# Merge configurations
cp CLAUDE.md CLAUDE.md.backup
kaizen-agentic install keepaTodofile
# Manually merge CLAUDE.md.backup content
```
### Workflow Disruption
**Issue**: New agents disrupt existing workflows.
**Solution**:
```bash
# Create compatibility extensions
kaizen-agentic extensions create workflow-compat keepaTodofile
# Configure extension to match existing workflow
```
## Success Metrics
### Technical Metrics
- ✅ Zero agent loading errors
- ✅ All tests passing
- ✅ No performance regressions
- ✅ Successful backup/restore capability
### Team Metrics
- ✅ Team adoption of new agents
- ✅ Maintained productivity during transition
- ✅ Positive feedback on new capabilities
- ✅ Reduced maintenance overhead
### Project Metrics
- ✅ Improved code quality metrics
- ✅ Better documentation coverage
- ✅ Enhanced development workflow efficiency
- ✅ Standardized agent ecosystem
## Conclusion
Successful integration of Kaizen agents into existing projects requires:
1. **Careful analysis** of existing agent systems
2. **Respectful approach** to existing project structure
3. **Gradual migration** with proper backup strategies
4. **Extension mechanisms** for preserving custom functionality
5. **Team communication** and training throughout the process
Follow these patterns and your integration will be smooth, reversible, and beneficial to your development workflow.
| 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 |

24
docs/agency-framework.md
View File

@@ -260,6 +260,8 @@ kaizen-agentic metrics show <agent> # Summary + recent executions
kaizen-agentic metrics list # Agents with metrics in project
kaizen-agentic metrics export <agent> # Dump executions.jsonl
kaizen-agentic metrics optimize [agent] # Run optimizer on project metrics (≥10 records)
kaizen-agentic metrics correlate <uid> # Helix Forge digest lookup (read-only)
kaizen-agentic metrics publish # Register optimizer output in artifact-store
```
`memory brief` includes a `## Performance Summary` when metrics exist (success
@@ -272,12 +274,28 @@ skip). Record outcomes at session close per
### Fleet correlation
Project metrics correlate with **Helix Forge** fleet session metrics in
`agentic-resources` via optional `helix_session_uid` (ADR-004). See
[wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md).
`agentic-resources` via optional `helix_session_uid` (ADR-004).
- `HELIX_SESSION_UID` (and related env vars) auto-merge on `metrics record`
- `metrics correlate <uid>` looks up fleet digest when `HELIX_STORE_DB` is set
See [integrations/helix-forge-correlation.md](integrations/helix-forge-correlation.md)
and [wiki/EcosystemIntegration.md](../wiki/EcosystemIntegration.md).
### Evidence retention
Optimizer outputs may be published to `artifact-store` (WP-0004 Part 3).
After `metrics optimize`, optionally publish optimizer outputs to **artifact-store**:
```bash
export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<write-token>
kaizen-agentic metrics publish --target .
```
Package uses `retention_class: raw-evidence` (180d). Local
`.kaizen/metrics/optimizer/` remains authoritative when publish is skipped.
Manifest: [integrations/optimizer-artifact-manifest.md](integrations/optimizer-artifact-manifest.md).
---

43
docs/integrations/activity-definitions/low-success-rate-review.md Normal file
View File

@@ -0,0 +1,43 @@
---
id: kaizen-low-success-rate-review
name: Low Agent Success Rate Review
enabled: false
owner: kaizen-agentic
governance: custodian
status: proposed
trigger:
type: event
event_type: kaizen.metrics.recorded
context_sources:
- type: event-payload
bind_to: context.metrics
---
# Low Agent Success Rate Review
When a project agent's rolling success rate drops below 0.8, create a review
task in issue-core for human or optimizer-agent follow-up.
```rule
id: flag-low-success-rate
condition: 'context.metrics.summary.success_rate < 0.8 && context.metrics.summary.execution_count >= 5'
action:
task_template: "Review {{context.metrics.agent}} success rate ({{context.metrics.summary.success_rate}})"
description: |
Agent {{context.metrics.agent}} in {{context.metrics.project}} has success_rate
below 0.8 over {{context.metrics.summary.execution_count}} executions.
Run: kaizen-agentic metrics show {{context.metrics.agent}}
Then: kaizen-agentic metrics optimize {{context.metrics.agent}}
target_repo: "{{context.metrics.project}}"
priority: high
labels: ["kaizen", "metrics", "review", "automated"]
```
**Threshold:** 0.8 success rate, minimum 5 executions (avoids noise on early pilots).
**CLI mapping:** Event emitter is future work; manual check today:
```bash
kaizen-agentic metrics show <agent> # inspect summary.success_rate
kaizen-agentic metrics optimize <agent>
```

41
docs/integrations/activity-definitions/post-install-metrics-scaffold.md Normal file
View File

@@ -0,0 +1,41 @@
---
id: kaizen-post-install-metrics-scaffold
name: Post-Install Metrics Scaffold Validation
enabled: false
owner: kaizen-agentic
governance: custodian
status: proposed
trigger:
type: event
event_type: kaizen.agent.installed
context_sources:
- type: event-payload
bind_to: context.install
---
# Post-Install Metrics Scaffold Validation
Fires when an agent is installed into a project. Verifies that memory and metrics
scaffolds exist for the installed agent.
```rule
id: validate-metrics-scaffold
condition: 'context.install.agent != ""'
action:
task_template: "Validate kaizen scaffold for {{context.install.agent}}"
description: |
In {{context.install.project_root}} verify:
- .kaizen/agents/{{context.install.agent}}/memory.md exists OR run:
kaizen-agentic memory init {{context.install.agent}}
- .kaizen/metrics/{{context.install.agent}}/ exists OR re-run init without --no-metrics
target_repo: "{{context.install.repo}}"
priority: low
labels: ["kaizen", "metrics", "scaffold", "automated"]
```
**CLI mapping:**
```bash
kaizen-agentic memory init <agent> # scaffolds memory + metrics by default
kaizen-agentic metrics list # confirms metrics directory after first record
```

44
docs/integrations/activity-definitions/weekly-metrics-optimize.md Normal file
View File

@@ -0,0 +1,44 @@
---
id: kaizen-weekly-metrics-optimize
name: Weekly Kaizen Metrics Optimization
enabled: false
owner: kaizen-agentic
governance: custodian
status: proposed
trigger:
type: cron
cron_expression: "0 8 * * 1"
timezone: Europe/Berlin
misfire_policy: skip
context_sources:
- type: shell
query: discover_kaizen_projects
params:
marker: .kaizen/metrics
bind_to: context.projects
---
# Weekly Kaizen Metrics Optimization
Runs every Monday 08:00 Berlin time on repos that contain `.kaizen/metrics/`.
Invokes the kaizen-agentic optimizer CLI per project.
```rule
id: run-weekly-optimizer
for_each: context.projects
bind_as: p
condition: 'p.has_metrics == true'
action:
task_template: "Run kaizen metrics optimize on {{p.repo}}"
description: |
cd {{p.root}} && kaizen-agentic metrics optimize
Optional: kaizen-agentic metrics publish (when artifact-store configured)
target_repo: "{{p.repo}}"
priority: medium
labels: ["kaizen", "metrics", "optimizer", "automated"]
```
**Activation:** sync this definition into activity-core via `make sync-activity-definitions`
after enabling the shell resolver for `discover_kaizen_projects`.
**CLI mapping:** `kaizen-agentic metrics optimize` (no agent filter = all agents with metrics).

44
docs/integrations/briefs/tdd-workflow-canon-brief.md Normal file
View File

@@ -0,0 +1,44 @@
# tdd-workflow — InfoTechCanon-style Brief
Compact agent brief derived from `agents/agent-tdd-workflow.md` (metrics pilot).
Reference for fleet-wide brief rollout.
```yaml
profile:
id: kaizen/tdd-workflow
version: "1.0"
domain: development-process
intent:
summary: Guide TDD8 ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycles
outcomes:
- Acceptance criteria covered by tests before PUBLISH
- Sidequests tracked without blocking parent issues
- Workspace integrated cleanly via make tdd-finish
metrics:
primary:
name: test_pass_rate
target: 1.0
measurement: passing_tests / total_tests at PUBLISH
secondary:
- name: cycle_time_s
measurement: session duration (execution_time_s)
collection:
storage: .kaizen/metrics/tdd-workflow/
frequency: per_execution
idempotency:
signals:
- current_issue.json workspace state
- idempotency_key on metrics record
session_protocol:
start: read .kaizen/agents/tdd-workflow/memory.md
close:
- update memory.md sections
- kaizen-agentic metrics record tdd-workflow
ecosystem:
fleet_correlation: helix_session_uid (ADR-004)
optimizer: kaizen-agentic metrics optimize
evidence: kaizen-agentic metrics publish (optional)
```
Full specification: [agents/agent-tdd-workflow.md](../../../agents/agent-tdd-workflow.md).
Pilot documentation: [wiki/AboutKaizenAgents.md](../../../wiki/AboutKaizenAgents.md).

32
docs/integrations/canon-template-mapping.md Normal file
View File

@@ -0,0 +1,32 @@
# KaizenAgentTemplate → InfoTechCanon Profile Mapping
Design note (WP-0004 Part 4). No runtime dependency on info-tech-canon.
## Section mapping
| `wiki/KaizenAgentTemplate.md` | InfoTechCanon profile outline |
|------------------------------|------------------------------|
| `specification.outcomes` | `profile.intent.outcomes[]` |
| `specification.constraints` | `profile.constraints.hard[]` / `soft[]` |
| `idempotency.detection` | `profile.idempotency.signals[]` |
| `idempotency.rollback` | `profile.safety.rollback` |
| `metrics.primary` | `profile.metrics.primary` |
| `metrics.secondary[]` | `profile.metrics.secondary[]` |
| `metrics.collection` | `profile.observability.collection` |
| `testing.unit_tests[]` | `profile.validation.unit[]` |
| `testing.integration_tests[]` | `profile.validation.integration[]` |
| `evolution.history` | `profile.evolution.changelog` |
| `evolution.optimization_hooks` | `profile.evolution.feedback_sources[]` |
## Validation hooks (future)
Extend `kaizen-agentic validate` to check:
1. Frontmatter contains `metrics.primary.name` when `memory: enabled`
2. Session-close block references `metrics record`
3. Required template sections present in agent body (warn, not fail)
## Reference pilot
`tdd-workflow` brief in [briefs/tdd-workflow-canon-brief.md](briefs/tdd-workflow-canon-brief.md)
demonstrates a compact canon-style export derived from the full agent spec.

103
docs/integrations/helix-forge-correlation.md Normal file
View File

@@ -0,0 +1,103 @@
# Helix Forge Correlation Contract
Cross-repo contract between **kaizen-agentic** (project metrics, ADR-004) and
**agentic-resources** (Helix Forge fleet session metrics).
## Purpose
Link a project-scoped agent execution record to the fleet session that produced
it, without duplicating session JSONL ingestion in kaizen-agentic.
## Layers
| Layer | Owner | Storage |
|-------|-------|---------|
| Project | kaizen-agentic | `.kaizen/metrics/<agent>/executions.jsonl` |
| Fleet | agentic-resources | Helix Forge digest store (`digests` table) |
## Correlation fields (ADR-004)
Optional on each project execution record:
```json
{
"helix_session_uid": "claude:17092961-…",
"repo": "kaizen-agentic",
"flavor": "claude",
"tokens": 12500,
"infra_overhead_share": 0.12
}
```
### Field mapping
| Helix Forge (`session_memory`) | ADR-004 project record |
|-------------------------------|------------------------|
| `Session.session_uid` | `helix_session_uid` |
| `Session.repo` | `repo` |
| `Session.flavor` | `flavor` |
| `digest.cost.input_tokens + output_tokens` | `tokens` |
| MCP tool share of `tool_histogram` | `infra_overhead_share` |
| `digest.outcome == "success"` | informs `success` at record time |
| `digest.cost.wall_clock_s` | complements `execution_time_s` |
## Population at session close
### Automatic (environment)
When Helix Forge capture is active in the same shell session:
```bash
export HELIX_SESSION_UID="claude:17092961-…"
export HELIX_REPO="kaizen-agentic"
export HELIX_FLAVOR="claude"
export HELIX_TOKENS="12500"
export HELIX_INFRA_OVERHEAD_SHARE="0.12"
kaizen-agentic metrics record tdd-workflow --success --time 4200 --quality 0.9
```
`metrics record` merges env vars into the execution record before append.
### Explicit (JSON)
```bash
echo '{
"success": true,
"execution_time_s": 4200,
"quality_score": 0.9,
"helix_session_uid": "claude:17092961-…",
"repo": "kaizen-agentic",
"flavor": "claude",
"tokens": 12500,
"infra_overhead_share": 0.12
}' | kaizen-agentic metrics record tdd-workflow --json
```
## Fleet lookup (read-only)
```bash
export HELIX_STORE_DB=~/.helix-forge/store.db # agentic-resources session store
kaizen-agentic metrics correlate claude:17092961-…
```
When `HELIX_STORE_DB` is unset, `metrics correlate` returns a **stub** response
documenting expected fields — no ingestion code runs in kaizen-agentic.
## Bidirectional references
| Document | Repo |
|----------|------|
| [ADR-004](../adr/ADR-004-project-metrics-convention.md) | kaizen-agentic |
| [wiki/EcosystemIntegration.md](../../wiki/EcosystemIntegration.md) | kaizen-agentic |
| [DESIGN-session-memory.md](https://github.com/coulomb/agentic-resources/blob/main/docs/DESIGN-session-memory.md) | agentic-resources |
| `session_memory/core/store.py` — `get_digest()` | agentic-resources |
agentic-resources should link back to this document from its session-memory design
notes when documenting downstream consumers of `session_uid`.
## Non-goals
- No Claude/Codex/Grok JSONL ingestion in kaizen-agentic
- No write path to Helix Forge from kaizen-agentic CLI
- No merge of fleet baselines into project `summary.json` (Coach may cite both)

41
docs/integrations/kontextual-wiki-ingestion-spike.md Normal file
View File

@@ -0,0 +1,41 @@
# kontextual-engine Wiki Ingestion Spike
Design note (WP-0004 Part 4). No runtime dependency.
## Proposed manifest
```yaml
ingestion:
source_repo: kaizen-agentic
asset_class: strategic-knowledge
paths:
- wiki/**/*.md
- INTENT.md
- docs/adr/ADR-*.md
exclude:
- wiki/**/xxx
metadata:
domain: custodian
topic_id: cee7bedf-2b48-46ef-8601-006474f2ad7a
producer: kaizen-agentic
refresh:
trigger: git-push-main
retention_class: operational-knowledge
```
## Rationale
- `wiki/` holds product narrative and integration contracts not suited for agent prompts alone
- ADRs are normative; kontextual-engine can index them for cross-repo retrieval
- Agent definitions (`agents/`) remain separate — executable personas vs strategic docs
## Open questions
1. Chunking strategy for `KaizenAgentTemplate.md` (section-aware vs whole-file)
2. Whether Coach synthesis outputs should be ingested as derived assets
3. Correlation with info-tech-canon profiles when both exist for one agent
## Next step
Dedicated workplan after WP-0004 baseline; evaluate kontextual-engine ingestion API
stability before hard dependency.

60
docs/integrations/optimizer-artifact-manifest.md Normal file
View File

@@ -0,0 +1,60 @@
# Optimizer Evidence Artifact Manifest
Package schema for `kaizen-agentic metrics publish` → **artifact-store**.
## Package identity
| Field | Value |
|-------|-------|
| `producer` | `kaizen-agentic` |
| `retention_class` | `raw-evidence` (180d default, ADR-004 aligned) |
| `name` | `kaizen-optimizer-<project-slug>` |
| `subject` | project directory name (override with `--subject`) |
## Files
| Relative path | Source | Media type |
|---------------|--------|------------|
| `optimizer/analysis.json` | `.kaizen/metrics/optimizer/analysis.json` | `application/json` |
| `optimizer/recommendations.jsonl` | `.kaizen/metrics/optimizer/recommendations.jsonl` | `application/x-ndjson` |
`recommendations.jsonl` is omitted from upload when absent (e.g. insufficient samples).
## Metadata (`POST /packages`)
```json
{
"schema": "kaizen-agentic/optimizer-evidence/v1",
"project": "demo-app",
"project_root": "/path/to/demo-app",
"producer": "kaizen-agentic",
"retention_class": "raw-evidence",
"retention_days": 180,
"optimized_at": "2026-06-18",
"agents": ["tdd-workflow", "coach"],
"files": [
"optimizer/analysis.json",
"optimizer/recommendations.jsonl"
]
}
```
## Publish workflow
```bash
# 1. Ensure optimizer has run
kaizen-agentic metrics optimize
# 2. Publish (artifact-store must be reachable)
export ARTIFACTSTORE_API_URL=http://127.0.0.1:8000
export ARTIFACTSTORE_API_TOKEN=<write-token>
kaizen-agentic metrics publish --target .
```
Local-only workflows skip publish; `.kaizen/metrics/optimizer/` remains authoritative.
## Related
- [artifact-store ingestion API](https://github.com/coulomb/artifact-store) — `POST /packages`, `/files`, `/finalize`
- [ADR-004](../adr/ADR-004-project-metrics-convention.md)
- [INTEGRATION_PATTERNS.md](../INTEGRATION_PATTERNS.md)