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:

```bash
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](PACKAGE_RELEASE.md) for pipx, local builds, and publishing.

## CLI Commands

### List Available Agents

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**:
   ```bash
   kaizen-agentic init my-web-app --template python-web
   cd my-web-app
   ```

2. **Set Up Development Environment**:
   ```bash
   make setup-complete
   source .venv/bin/activate
   ```

3. **Start Development**:
   ```bash
   make test          # Run tests
   make lint          # Check code quality
   make format        # Format code
   ```

### Adding Agents to Existing Project

1. **Install Needed Agents**:
   ```bash
   kaizen-agentic install todo-keeper changelog-keeper
   ```

2. **Verify Installation**:
   ```bash
   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**:
   ```bash
   kaizen-agentic status
   ```

2. **Update All Agents**:
   ```bash
   kaizen-agentic update
   ```

3. **Validate After Update**:
   ```bash
   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:

```bash
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:

```python
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:

```python
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:

```yaml
---
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**:
```bash
# Check available agents
kaizen-agentic list

# Validate registry
kaizen-agentic validate
```

**Installation Failures**:
```bash
# Check target directory permissions
# Verify agent file integrity
kaizen-agentic validate --target /path/to/project
```

**Update Problems**:
```bash
# 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**:
   ```bash
   ls agents/agent-*.md
   ```

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

3. **Validate Current Setup**:
   ```bash
   kaizen-agentic validate
   ```

4. **Update to Standard Agents**:
   ```bash
   kaizen-agentic update
   ```

### Between Versions

When updating Kaizen Agentic versions:

1. **Backup Current Agents**:
   ```bash
   cp -r agents/ agents_backup/
   ```

2. **Update Package**:
   ```bash
   pip install --upgrade kaizen-agentic
   ```

3. **Update Agents**:
   ```bash
   kaizen-agentic update
   ```

4. **Validate**:
   ```bash
   kaizen-agentic validate
   ```

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