kaizen-agentic/docs/AGENT_DISTRIBUTION.md

Agent Distribution Guide

This guide explains how to use the Kaizen Agentic agent distribution system to share specialized agents across projects.

Overview

The Kaizen Agentic framework provides a comprehensive system for distributing and managing AI agents across multiple projects. This enables:

• Reusable Agents: Share specialized agents between projects
• Consistent Workflows: Maintain the same development patterns across teams
• Easy Updates: Update agents across all projects from a central registry
• Template-Based Initialization: Start new projects with predefined agent collections

Installation

Install the Kaizen Agentic package from the Coulomb Gitea PyPI registry:

export GITEA_PACKAGE_USER=<gitea-user>
export GITEA_PACKAGE_TOKEN=<package-token>

pip install kaizen-agentic \
  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"

This provides the kaizen-agentic CLI tool for managing agents. See PACKAGE_RELEASE.md for pipx, local builds, and publishing.

CLI Commands

List Available Agents

# List all available agents
kaizen-agentic list

# List agents by category
kaizen-agentic list --category project-management

# List with detailed information
kaizen-agentic list --verbose

Initialize New Projects

# Initialize with default Python template
kaizen-agentic init my-project

# Use specific template
kaizen-agentic init web-app --template python-web

# Use custom agent selection
kaizen-agentic init data-project --agents todo-keeper,datamodel-optimization,testing-efficiency

# Initialize in specific directory
kaizen-agentic init my-project --parent-dir ~/projects

Install Agents in Existing Projects

# Install specific agents
kaizen-agentic install todo-keeper changelog-keeper

# Install to specific directory
kaizen-agentic install tdd-workflow --target ~/my-project

# Install without backup
kaizen-agentic install code-refactoring --no-backup

# Install without updating documentation
kaizen-agentic install testing-efficiency --no-docs

Manage Installed Agents

# List installed agents
kaizen-agentic status

# Update all installed agents
kaizen-agentic update

# Update specific agents
kaizen-agentic update todo-keeper changelog-keeper

# Remove agents
kaizen-agentic remove old-agent-name

# Validate agents
kaizen-agentic validate

Project Templates

# List available templates
kaizen-agentic templates

# Available templates:
# - python-basic: Basic Python project setup
# - python-web: Web application development
# - python-cli: Command-line tool development
# - python-data: Data science and analysis
# - comprehensive: All available agents

Project Structure

When you install agents, they're organized in your project as follows:

my-project/
├── agents/                    # Installed agent definitions
│   ├── agent-todo-keeper.md
│   ├── agent-changelog-keeper.md
│   └── agent-tdd-workflow.md
├── src/
├── tests/
├── CLAUDE.md                  # Updated with agent information
├── Makefile                   # Enhanced with agent targets
└── pyproject.toml

Agent Categories

Agents are organized into categories for easy discovery:

Project Management

• todo-keeper: Manages TODO.md files following Keep a Todofile format
• changelog-keeper: Maintains CHANGELOG.md files following Keep a Changelog format
• contributing-keeper: Creates and updates CONTRIBUTING.md files
• project-assistant: General project management and coordination

Development Process

• tdd-workflow: Test-driven development workflow guidance
• requirements-engineering: Requirements analysis and documentation
• test-maintenance: Test suite maintenance and optimization
• priority-evaluation: Feature and task prioritization

Code Quality

• code-refactoring: Code improvement and refactoring guidance
• agent-optimization: Agent definition optimization and improvement
• datamodel-optimization: Data model design and optimization
• tooling-optimization: Development tool configuration and optimization

Infrastructure

• setup-repository: Repository initialization and standards compliance
• claude-documentation: Claude Code configuration and documentation
• testing-efficiency: Testing infrastructure optimization
• wisdom-encouragement: Development philosophy and best practices

Usage Patterns

New Project Setup

1. Initialize Project:

   kaizen-agentic init my-web-app --template python-web
   cd my-web-app
   

2. Set Up Development Environment:

   make setup-complete
   source .venv/bin/activate
   

3. Start Development:

   make test          # Run tests
   make lint          # Check code quality
   make format        # Format code
   

Adding Agents to Existing Project

1. Install Needed Agents:

   kaizen-agentic install todo-keeper changelog-keeper
   

2. Verify Installation:

   kaizen-agentic status
   kaizen-agentic validate
   

3. Use Agents:

   • Reference agents in Claude Code conversations
   • Use agent-specific Makefile targets
   • Follow agent-guided workflows

Maintaining Agent Updates

1. Check for Updates:

   kaizen-agentic status
   

2. Update All Agents:

   kaizen-agentic update
   

3. Validate After Update:

   kaizen-agentic validate
   

Integration with Development Tools

Claude Code Integration

Agents automatically integrate with Claude Code:

• CLAUDE.md: Updated with agent descriptions and usage
• Agent References: Use agents by name in Claude conversations
• Workflow Integration: Agents guide Claude Code interactions

Makefile Integration

The CLI automatically adds agent management targets:

make agents-list      # List installed agents
make agents-update    # Update to latest versions
make agents-validate  # Validate agent definitions

Documentation Integration

Agents automatically update project documentation:

• README.md: Enhanced with agent information
• CONTRIBUTING.md: Updated with agent-assisted workflows
• CLAUDE.md: Complete agent catalog and usage instructions

Advanced Usage

Custom Agent Templates

Create custom templates by modifying the registry:

from kaizen_agentic import AgentRegistry

registry = AgentRegistry("path/to/agents")

# Add custom template
custom_template = {
    "my-template": [
        "todo-keeper",
        "custom-agent",
        "code-refactoring"
    ]
}

templates = registry.get_agent_templates()
templates.update(custom_template)

Programmatic Agent Management

Use the Python API for custom integrations:

from kaizen_agentic import AgentInstaller, AgentRegistry, InstallationConfig
from pathlib import Path

# Set up registry and installer
registry = AgentRegistry("agents/")
installer = AgentInstaller(registry)

# Configure installation
config = InstallationConfig(
    target_dir=Path("my-project"),
    claude_config_path=Path("my-project/CLAUDE.md"),
    update_docs=True
)

# Install agents
results = installer.install_agents(["todo-keeper", "tdd-workflow"], config)

Agent Development

Create new agents by following the standard format:

---
name: my-custom-agent
description: Custom agent for specific needs
model: inherit
---

# My Custom Agent

## Instructions

[Agent instructions and capabilities]

## Authority and Scope

[What the agent can and cannot do]

## Response Guidelines

[How the agent should respond and behave]

Best Practices

Agent Selection

1. Start Small: Begin with basic agents (todo-keeper, changelog-keeper)
2. Add Gradually: Introduce more specialized agents as needed
3. Match Project Type: Use appropriate templates for your project type
4. Consider Dependencies: Let the system resolve agent dependencies

Maintenance

1. Regular Updates: Update agents monthly or before major releases
2. Validation: Always validate after updates or changes
3. Backup: Keep backups when experimenting with new agents
4. Documentation: Keep CLAUDE.md and project docs updated

Team Coordination

1. Shared Templates: Agree on standard templates for your team
2. Agent Standards: Establish which agents are required/optional
3. Update Schedules: Coordinate agent updates across team projects
4. Training: Ensure team members understand agent capabilities

Troubleshooting

Common Issues

Agent Not Found:

# Check available agents
kaizen-agentic list

# Validate registry
kaizen-agentic validate

Installation Failures:

# Check target directory permissions
# Verify agent file integrity
kaizen-agentic validate --target /path/to/project

Update Problems:

# Force reinstall
kaizen-agentic remove problematic-agent
kaizen-agentic install problematic-agent

Getting Help

1. Validate Configuration: Use kaizen-agentic validate
2. Check Status: Use kaizen-agentic status
3. Review Logs: Check command output for error details
4. Community Support: Refer to project documentation and issues

Migration Guide

From Manual Agent Management

If you're currently managing agents manually:

1. Inventory Current Agents:

   ls agents/agent-*.md
   

2. Install Package (same as Installation section above).

3. Validate Current Setup:

   kaizen-agentic validate
   

4. Update to Standard Agents:

   kaizen-agentic update
   

Between Versions

When updating Kaizen Agentic versions:

1. Backup Current Agents:

   cp -r agents/ agents_backup/
   

2. Update Package:

   pip install --upgrade kaizen-agentic
   

3. Update Agents:

   kaizen-agentic update
   

4. Validate:

   kaizen-agentic validate
   

This distribution system makes it easy to share and maintain consistent development workflows across all your projects using specialized AI agents.