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.

👋 New User? Start with our Hello World Tutorial for a complete step-by-step walkthrough.

Quick Start

1. Install the Package

Option A: From Source (Development Mode)

# Clone the repository
git clone https://github.com/kaizen-agentic/kaizen-agentic.git
cd kaizen-agentic

# Set up development environment
make setup-complete

# Install CLI tool (local to project)
make agents-install-cli

# Activate virtual environment (required for each session)
source .venv/bin/activate

Option B: Local Package Testing (PyPI-equivalent)

# Clone the repository and build package
git clone https://github.com/kaizen-agentic/kaizen-agentic.git
cd kaizen-agentic
make setup-complete

# Build and install from local package (local to project)
python3 -m build
make install-local

# Activate virtual environment (required for each session)
source .venv/bin/activate

Option C: Global Installation (Available from any directory)

# Clone the repository and build package
git clone https://github.com/kaizen-agentic/kaizen-agentic.git
cd kaizen-agentic
make setup-complete

# Build and install globally
python3 -m build
make install-global

# No virtual environment activation needed
# CLI available from any directory

Option D: From Gitea PyPI (v1.1.0+)

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

# or global CLI via pipx
pipx install kaizen-agentic \
  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"

📦 Registry: Published on the Coulomb Gitea PyPI registry. Dependencies resolve from public PyPI via --extra-index-url. See PACKAGE_RELEASE.md.

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 setupRepository keepaTodofile keepaChangelog

# The setupRepository 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 keepaTodofile keepaChangelog 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)
agents-list:
	@echo "Installed agents:"
	@ls agents/ 2>/dev/null | grep agent- | sed 's/agent-//g' | sed 's/.md//g' | sort

agents-update:
	@kaizen-agentic update

agents-validate:
	@kaizen-agentic validate

agents-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 agents-list'
kaizen-agentic status

# Instead of 'make agents-update'
kaizen-agentic update

# Instead of 'make agents-validate'
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
          --extra-index-url "https://${{ secrets.GITEA_PACKAGE_USER }}:${{ secrets.GITEA_PACKAGE_TOKEN }}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
      - 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 keepaTodofile

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-keepaTodofile.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
# see Option D for GITEA_PACKAGE_USER / GITEA_PACKAGE_TOKEN and --extra-index-url
pip install kaizen-agentic
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 from Gitea PyPI (same credentials as Option D)
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/"

# Or if using virtual env:
source .venv/bin/activate
pip install kaizen-agentic \
  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"

"No agents directory found"

# Install some agents first
kaizen-agentic install keepaTodofile

# Or initialize a new project
kaizen-agentic init . --agents keepaTodofile,keepaChangelog

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