coulomb/kaizen-agentic
2
0
Fork 0
Code Issues 4 Pull Requests Actions 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

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 |