kaizen-agentic/docs/GETTING_STARTED.md

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

pip install kaizen-agentic

This gives you the kaizen-agentic command globally.

2. Verify Installation

kaizen-agentic --version
kaizen-agentic list

You should see the available agents listed.

For New Projects

Option A: Initialize with Agents (Recommended)

# 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

# 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

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

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

{
  "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:

[project.optional-dependencies]
agents = ["kaizen-agentic>=0.1.0"]

[tool.setuptools]
# Include agents in package data if needed

Step 3: Update Documentation

# 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

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

{
  "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

# Add to .git/hooks/pre-commit
#!/bin/sh
kaizen-agentic validate

3. CI/CD Integration

GitHub Actions (.github/workflows/agents.yml):

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

# 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

# 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

# Add agents commands to package.json scripts
npm run agents:status    # -> kaizen-agentic status
npm run agents:update    # -> kaizen-agentic update

Ruby Projects

# Add to Rakefile
task :agents_status do
  system('kaizen-agentic status')
end

task :agents_update do
  system('kaizen-agentic update')
end

Java/Gradle Projects

// 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

# 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

# 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

# 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

# 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

# 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

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

# Install the package
pip install kaizen-agentic

# Or if using virtual env:
source .venv/bin/activate
pip install kaizen-agentic

"No agents directory found"

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

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