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:
410
docs/GETTING_STARTED.md
Normal file
410
docs/GETTING_STARTED.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# Getting Started with Kaizen Agentic Agents
|
||||
|
||||
This guide walks you through using Kaizen Agentic agents in any project, from initial installation to full integration.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install the Package
|
||||
|
||||
```bash
|
||||
pip install kaizen-agentic
|
||||
```
|
||||
|
||||
This gives you the `kaizen-agentic` command globally.
|
||||
|
||||
### 2. Verify Installation
|
||||
|
||||
```bash
|
||||
kaizen-agentic --version
|
||||
kaizen-agentic list
|
||||
```
|
||||
|
||||
You should see the available agents listed.
|
||||
|
||||
## For New Projects
|
||||
|
||||
### Option A: Initialize with Agents (Recommended)
|
||||
|
||||
```bash
|
||||
# Create a new project with agents included
|
||||
kaizen-agentic init my-project --template python-web
|
||||
|
||||
# Navigate to project
|
||||
cd my-project
|
||||
|
||||
# Set up development environment (agents provide this Makefile)
|
||||
make setup-complete
|
||||
|
||||
# You now have all the Makefile targets available!
|
||||
make help
|
||||
```
|
||||
|
||||
### Option B: Manual Project Setup
|
||||
|
||||
```bash
|
||||
# Create project directory
|
||||
mkdir my-project
|
||||
cd my-project
|
||||
|
||||
# Initialize git
|
||||
git init
|
||||
|
||||
# Install agents
|
||||
kaizen-agentic install setup-repository todo-keeper changelog-keeper
|
||||
|
||||
# The setup-repository agent can create the full project structure
|
||||
# Use it via Claude Code or manually follow its patterns
|
||||
```
|
||||
|
||||
## For Existing Projects
|
||||
|
||||
### Step 1: Install Agents
|
||||
|
||||
```bash
|
||||
# Navigate to your existing project
|
||||
cd /path/to/your/project
|
||||
|
||||
# Install relevant agents
|
||||
kaizen-agentic install todo-keeper changelog-keeper tdd-workflow
|
||||
|
||||
# Check what was installed
|
||||
kaizen-agentic status
|
||||
```
|
||||
|
||||
### Step 2: Integrate with Build System
|
||||
|
||||
The agents will create/update files, but you need to integrate with your build system:
|
||||
|
||||
#### If you have a Makefile:
|
||||
```bash
|
||||
# Add these targets to your existing Makefile:
|
||||
cat >> Makefile << 'EOF'
|
||||
|
||||
# Agent Management (added by kaizen-agentic)
|
||||
list-agents:
|
||||
@echo "Installed agents:"
|
||||
@ls agents/ 2>/dev/null | grep agent- | sed 's/agent-//g' | sed 's/.md//g' | sort
|
||||
|
||||
update-agents:
|
||||
@kaizen-agentic update
|
||||
|
||||
validate-agents:
|
||||
@kaizen-agentic validate
|
||||
|
||||
agent-status:
|
||||
@kaizen-agentic status
|
||||
EOF
|
||||
```
|
||||
|
||||
#### If you use npm/package.json:
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"agents:list": "ls agents/ | grep agent- | sed 's/agent-//g' | sed 's/.md//g'",
|
||||
"agents:update": "kaizen-agentic update",
|
||||
"agents:validate": "kaizen-agentic validate",
|
||||
"agents:status": "kaizen-agentic status"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### If you use Python/pyproject.toml:
|
||||
```toml
|
||||
[project.optional-dependencies]
|
||||
agents = ["kaizen-agentic>=0.1.0"]
|
||||
|
||||
[tool.setuptools]
|
||||
# Include agents in package data if needed
|
||||
```
|
||||
|
||||
### Step 3: Update Documentation
|
||||
|
||||
```bash
|
||||
# Agents automatically update CLAUDE.md, but you can also manually check:
|
||||
kaizen-agentic status
|
||||
|
||||
# Update your README.md to mention agent usage:
|
||||
echo "
|
||||
## AI Agents
|
||||
|
||||
This project uses Kaizen Agentic agents for development workflow automation.
|
||||
|
||||
- List agents: \`kaizen-agentic list\`
|
||||
- Check status: \`kaizen-agentic status\`
|
||||
- Update agents: \`kaizen-agentic update\`
|
||||
|
||||
See CLAUDE.md for detailed agent information.
|
||||
" >> README.md
|
||||
```
|
||||
|
||||
## Working Without Make Targets
|
||||
|
||||
If you're in a project without the Kaizen Agentic Makefile targets, you can still use all functionality:
|
||||
|
||||
### Direct CLI Usage
|
||||
|
||||
```bash
|
||||
# Instead of 'make list-agents'
|
||||
kaizen-agentic status
|
||||
|
||||
# Instead of 'make update-agents'
|
||||
kaizen-agentic update
|
||||
|
||||
# Instead of 'make validate-agents'
|
||||
kaizen-agentic validate
|
||||
|
||||
# Install new agents
|
||||
kaizen-agentic install code-refactoring testing-efficiency
|
||||
|
||||
# Remove agents you don't need
|
||||
kaizen-agentic remove old-agent-name
|
||||
```
|
||||
|
||||
### Integration Patterns
|
||||
|
||||
#### 1. IDE Integration
|
||||
Most IDEs can run arbitrary commands. Add these as external tools:
|
||||
|
||||
**VS Code tasks.json:**
|
||||
```json
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "List Agents",
|
||||
"type": "shell",
|
||||
"command": "kaizen-agentic",
|
||||
"args": ["status"],
|
||||
"group": "build"
|
||||
},
|
||||
{
|
||||
"label": "Update Agents",
|
||||
"type": "shell",
|
||||
"command": "kaizen-agentic",
|
||||
"args": ["update"],
|
||||
"group": "build"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Git Hooks Integration
|
||||
```bash
|
||||
# Add to .git/hooks/pre-commit
|
||||
#!/bin/sh
|
||||
kaizen-agentic validate
|
||||
```
|
||||
|
||||
#### 3. CI/CD Integration
|
||||
|
||||
**GitHub Actions (.github/workflows/agents.yml):**
|
||||
```yaml
|
||||
name: Validate Agents
|
||||
on: [push, pull_request]
|
||||
jobs:
|
||||
validate-agents:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.8'
|
||||
- run: pip install kaizen-agentic
|
||||
- run: kaizen-agentic validate
|
||||
```
|
||||
|
||||
#### 4. Shell Aliases
|
||||
```bash
|
||||
# Add to your ~/.bashrc or ~/.zshrc
|
||||
alias ka="kaizen-agentic"
|
||||
alias ka-status="kaizen-agentic status"
|
||||
alias ka-update="kaizen-agentic update"
|
||||
alias ka-list="kaizen-agentic list"
|
||||
|
||||
# Now you can use:
|
||||
# ka status
|
||||
# ka update
|
||||
# ka install todo-keeper
|
||||
```
|
||||
|
||||
## Language-Specific Integration
|
||||
|
||||
### Python Projects
|
||||
```bash
|
||||
# Add to requirements-dev.txt or pyproject.toml
|
||||
kaizen-agentic>=0.1.0
|
||||
|
||||
# Use in scripts
|
||||
python -c "
|
||||
import subprocess
|
||||
subprocess.run(['kaizen-agentic', 'status'])
|
||||
"
|
||||
```
|
||||
|
||||
### Node.js Projects
|
||||
```bash
|
||||
# Add agents commands to package.json scripts
|
||||
npm run agents:status # -> kaizen-agentic status
|
||||
npm run agents:update # -> kaizen-agentic update
|
||||
```
|
||||
|
||||
### Ruby Projects
|
||||
```ruby
|
||||
# Add to Rakefile
|
||||
task :agents_status do
|
||||
system('kaizen-agentic status')
|
||||
end
|
||||
|
||||
task :agents_update do
|
||||
system('kaizen-agentic update')
|
||||
end
|
||||
```
|
||||
|
||||
### Java/Gradle Projects
|
||||
```gradle
|
||||
// Add to build.gradle
|
||||
task agentsStatus(type: Exec) {
|
||||
commandLine 'kaizen-agentic', 'status'
|
||||
}
|
||||
|
||||
task agentsUpdate(type: Exec) {
|
||||
commandLine 'kaizen-agentic', 'update'
|
||||
}
|
||||
```
|
||||
|
||||
## Discovery and Learning
|
||||
|
||||
### Find Relevant Agents
|
||||
```bash
|
||||
# Browse all available agents
|
||||
kaizen-agentic list --verbose
|
||||
|
||||
# Look at specific categories
|
||||
kaizen-agentic list --category project-management
|
||||
kaizen-agentic list --category testing
|
||||
kaizen-agentic list --category code-quality
|
||||
|
||||
# See what templates include
|
||||
kaizen-agentic templates
|
||||
```
|
||||
|
||||
### Understanding Agents
|
||||
```bash
|
||||
# Check what's installed in your project
|
||||
kaizen-agentic status
|
||||
|
||||
# Read agent files directly
|
||||
ls agents/
|
||||
cat agents/agent-todo-keeper.md
|
||||
|
||||
# Validate your setup
|
||||
kaizen-agentic validate
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
```bash
|
||||
# General help
|
||||
kaizen-agentic --help
|
||||
|
||||
# Command-specific help
|
||||
kaizen-agentic install --help
|
||||
kaizen-agentic init --help
|
||||
|
||||
# Check version
|
||||
kaizen-agentic --version
|
||||
```
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Starting a New Feature
|
||||
|
||||
```bash
|
||||
# 1. Check current agents
|
||||
kaizen-agentic status
|
||||
|
||||
# 2. Add agents for the feature (if needed)
|
||||
kaizen-agentic install requirements-engineering code-refactoring
|
||||
|
||||
# 3. Use agents in Claude Code
|
||||
# Reference them by name in your conversations
|
||||
|
||||
# 4. Update project documentation as you work
|
||||
```
|
||||
|
||||
### Maintaining Agents
|
||||
|
||||
```bash
|
||||
# Weekly agent maintenance
|
||||
kaizen-agentic update
|
||||
kaizen-agentic validate
|
||||
|
||||
# Before major releases
|
||||
kaizen-agentic status
|
||||
# Review agent output and update project docs accordingly
|
||||
```
|
||||
|
||||
### Team Onboarding
|
||||
|
||||
```bash
|
||||
# New team member setup
|
||||
git clone project-repo
|
||||
cd project-repo
|
||||
pip install kaizen-agentic # or add to requirements
|
||||
kaizen-agentic status # See what agents are used
|
||||
kaizen-agentic validate # Verify everything works
|
||||
|
||||
# Read the agent documentation
|
||||
cat CLAUDE.md
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"Command not found: kaizen-agentic"**
|
||||
```bash
|
||||
# Install the package
|
||||
pip install kaizen-agentic
|
||||
|
||||
# Or if using virtual env:
|
||||
source .venv/bin/activate
|
||||
pip install kaizen-agentic
|
||||
```
|
||||
|
||||
**"No agents directory found"**
|
||||
```bash
|
||||
# Install some agents first
|
||||
kaizen-agentic install todo-keeper
|
||||
|
||||
# Or initialize a new project
|
||||
kaizen-agentic init . --agents todo-keeper,changelog-keeper
|
||||
```
|
||||
|
||||
**"Agent validation fails"**
|
||||
```bash
|
||||
# Check specific errors
|
||||
kaizen-agentic validate
|
||||
|
||||
# Reinstall problematic agents
|
||||
kaizen-agentic remove problematic-agent
|
||||
kaizen-agentic install problematic-agent
|
||||
```
|
||||
|
||||
### Getting Support
|
||||
|
||||
1. **Check Status**: `kaizen-agentic status`
|
||||
2. **Validate Setup**: `kaizen-agentic validate`
|
||||
3. **Review Documentation**: Check CLAUDE.md and agent files
|
||||
4. **Community Help**: Refer to project issues and documentation
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once you have agents installed:
|
||||
|
||||
1. **Use them in Claude Code**: Reference agents by name in conversations
|
||||
2. **Follow agent workflows**: Let agents guide your development process
|
||||
3. **Keep them updated**: Regular `kaizen-agentic update`
|
||||
4. **Share with team**: Document which agents your project uses
|
||||
5. **Contribute back**: Report issues and suggest improvements
|
||||
|
||||
The key insight is that **you don't need the Makefile targets to use agents effectively** - the `kaizen-agentic` CLI provides all the functionality you need. The Makefile targets are just convenient shortcuts for projects that have them.
|
||||
Reference in New Issue
Block a user