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](HELLO_WORLD_TUTORIAL.md) for a complete step-by-step walkthrough.

## Quick Start

### 1. Install the Package

**Option A: From Source (Development Mode)**

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

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

```bash
# 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+)**

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

# 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](PACKAGE_RELEASE.md).

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

```bash
# 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:
```bash
# 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:
```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 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:**
```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
          --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
```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 keepaTodofile
```

## 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-keepaTodofile.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
# 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"**
```bash
# 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"**
```bash
# Install some agents first
kaizen-agentic install keepaTodofile

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

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