Implement hybrid agent distribution system
Complete implementation of the agent distribution framework including: CORE INFRASTRUCTURE: - AgentRegistry: Agent discovery, categorization, and dependency management - AgentInstaller: Agent installation, updates, and removal with safety measures - ProjectInitializer: Template-based project initialization with agent integration - CLI Tool: Comprehensive kaizen-agentic command-line interface DISTRIBUTION FEATURES: - Python package distribution with console script entry point - Agent categorization (project-management, development-process, code-quality, etc.) - Project templates (python-basic, python-web, python-cli, python-data, comprehensive) - Dependency resolution and validation - Idempotent operations with backup and rollback support CLI COMMANDS: - kaizen-agentic init: Initialize new projects with agents - kaizen-agentic install/update/remove: Manage agents in existing projects - kaizen-agentic list/status/validate: Discovery and maintenance - kaizen-agentic templates: Project template management INTEGRATION & DOCUMENTATION: - Makefile targets for agent management (list-agents, update-agents, etc.) - Automatic Claude Code configuration updates (CLAUDE.md) - Comprehensive documentation (GETTING_STARTED, AGENT_DISTRIBUTION, CLI_CHEAT_SHEET) - Multi-language build system integration examples - Complete test coverage for all components PACKAGE STRUCTURE: - Console script: kaizen-agentic command available globally - Package data: All agents included for distribution - Dependencies: click, pyyaml for CLI and parsing - Testing: Comprehensive test suite for registry and installer This enables sharing specialized AI agents across projects with easy installation, updates, and management through both CLI and integrated Makefile targets. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
415
docs/AGENT_DISTRIBUTION.md
Normal file
415
docs/AGENT_DISTRIBUTION.md
Normal file
@@ -0,0 +1,415 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
pip install kaizen-agentic
|
||||
```
|
||||
|
||||
This provides the `kaizen-agentic` CLI tool for managing agents.
|
||||
|
||||
## 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 list-agents # List installed agents
|
||||
make update-agents # Update to latest versions
|
||||
make validate-agents # 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**:
|
||||
```bash
|
||||
pip install kaizen-agentic
|
||||
```
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user