kaizen-agentic/docs/INTEGRATION_PATTERNS.md

Integration Patterns for Existing Projects

This guide documents proven patterns for integrating Kaizen Agentic agents into existing projects that already have agent systems.

Overview

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

Scenario 1: Clean Integration (No Existing Agents)

When to use: Project has no existing agent systems.

Pattern: Direct installation

kaizen-agentic init . --agents keepaTodofile,keepaChangelog,tdd-workflow

Benefits:

• Straightforward setup
• No conflicts to resolve
• Full Kaizen agent functionality

Scenario 2: Claude Code Integration

When to use: Project already uses Claude Code with CLAUDE.md.

Pattern: Respectful coexistence

# 1. Detect existing setup
kaizen-agentic detect

# 2. Install compatible agents
kaizen-agentic install keepaTodofile keepaChangelog

# 3. Update CLAUDE.md with new agent references

Considerations:

• Preserve existing CLAUDE.md content
• Add Kaizen agent references to existing documentation
• Maintain Claude Code workflow compatibility

Scenario 3: Custom Agent Replacement

When to use: Project has custom agents that overlap with Kaizen functionality.

Pattern: Gradual migration with backup

# 1. Analyze existing agents
kaizen-agentic detect --detailed

# 2. Create migration plan
kaizen-agentic migrate --dry-run

# 3. Execute migration with backup
kaizen-agentic migrate

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

Scenario 4: Hybrid Coexistence

When to use: Project has essential custom agents that cannot be replaced.

Pattern: Namespace separation

# 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

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

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

# 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

# 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

# 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

# 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

# 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

# Week 1: Analysis
kaizen-agentic detect --detailed
kaizen-agentic migrate --dry-run

# Decision point: Continue or modify approach

Phase 2: Infrastructure Agents

# Week 2: Core infrastructure
kaizen-agentic install setupRepository
# Test and validate before proceeding

Phase 3: Core Functionality

# Week 3: Essential agents
kaizen-agentic install keepaTodofile keepaChangelog
# Create extensions for custom functionality

Phase 4: Advanced Features

# Week 4: Specialized agents
kaizen-agentic install tdd-workflow code-refactoring
# Full integration testing

Rollback Strategy

Pattern: Versioned backups with restore capability

# 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

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

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

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

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