kaizen-agentic/docs/HELLO_WORLD_TUTORIAL.md

# Hello World Tutorial - Your First Kaizen Agentic Project

This step-by-step tutorial will guide you through creating your first project with Kaizen Agentic agents. By the end, you'll have a working Python project with tests, code quality tools, and AI agents to help with development.

## Prerequisites

- Python 3.8 or higher
- Basic knowledge of command line

## Step 1: Install Kaizen Agentic

From the Coulomb Gitea PyPI registry (dependencies resolve from public PyPI):

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

See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md) for pipx and release details.

Verify the installation:

```bash
kaizen-agentic --version
kaizen-agentic list
```

You should see a list of available agents.

## Step 2: Create Your First Project

```bash
# Create a new project called "hello-world"
kaizen-agentic init hello-world --template python-basic

# Navigate to the project
cd hello-world
```

**What just happened?**
- Created a complete Python project structure
- Installed 3 essential agents: setupRepository, keepaTodofile, keepaChangelog
- Generated Makefile with development commands
- Set up pyproject.toml with modern Python configuration
- Created README.md with project documentation

## Step 3: Set Up Development Environment

```bash
# Set up virtual environment and install dependencies
make setup-complete
```

This command:
- Creates a Python virtual environment (`.venv/`)
- Installs development tools (pytest, black, flake8, mypy)
- Sets up the project for development

## Step 4: Explore Your Project Structure

```bash
# See what was created
ls -la

# Check the available make commands
make help
```

Your project now has:
```
hello-world/
├── src/hello_world/          # Your Python package
├── tests/                    # Test files
├── agents/                   # AI agents for development help
├── docs/                     # Documentation
├── Makefile                  # Development commands
├── pyproject.toml           # Python project configuration
├── README.md                # Project documentation
└── CLAUDE.md                # Agent configuration for Claude Code
```

## Step 5: Create Your First Function

Create a simple "Hello World" module:

```bash
# Create the main hello.py file
cat > src/hello_world/hello.py << 'EOF'
def hello_world() -> str:
    """Return a friendly greeting."""
    return "Hello, World!"


def main() -> None:
    """Main entry point."""
    print(hello_world())


if __name__ == "__main__":
    main()
EOF
```

## Step 6: Write Your First Test

```bash
# Create a test file
cat > tests/test_hello.py << 'EOF'
def test_hello_world():
    """Test the hello_world function."""
    from hello_world.hello import hello_world
    assert hello_world() == "Hello, World!"


def test_main_function_exists():
    """Test that main function exists."""
    from hello_world.hello import main
    # Just check it's callable
    assert callable(main)
EOF
```

## Step 7: Run Your Tests

```bash
make test
```

You should see:
```
============================= test session starts ==============================
...
tests/test_hello.py::test_hello_world PASSED                              [100%]
tests/test_hello.py::test_main_function_exists PASSED                     [100%]

============================== 2 passed in 0.02s
```

## Step 8: Check Code Quality

```bash
# Check code formatting and style
make lint

# Auto-format your code
make format

# Run lint again to see improvements
make lint
```

## Step 9: Run Your Program

```bash
# Activate virtual environment
source .venv/bin/activate

# Run your hello world program
python src/hello_world/hello.py
```

You should see: `Hello, World!`

## Step 10: Explore AI Agents

Your project includes helpful AI agents:

```bash
# See installed agents (when kaizen-agentic is available)
ls agents/

# View agent documentation
cat agents/agent-keepaTodofile.md
```

**What do these agents do?**
- **setupRepository**: Helps set up Python projects following best practices
- **keepaTodofile**: Manages TODO.md files for task tracking
- **keepaChangelog**: Maintains CHANGELOG.md files for version history

## Step 11: Development Workflow

Your typical development workflow is now:

```bash
# 1. Write code
vim src/hello_world/my_feature.py

# 2. Write tests
vim tests/test_my_feature.py

# 3. Run tests
make test

# 4. Check code quality
make lint

# 5. Format code if needed
make format

# 6. Commit changes
git add .
git commit -m "Add my new feature"
```

## Step 12: Add More Agents (Optional)

As your project grows, add more specialized agents:

```bash
# Add TDD workflow agent
kaizen-agentic install tdd-workflow

# Add code refactoring agent
kaizen-agentic install code-refactoring

# Check what's installed
kaizen-agentic status
```

## Next Steps

🎉 **Congratulations!** You've created your first Kaizen Agentic project.

**Continue learning:**

1. **Read the docs**: Check out [GETTING_STARTED.md](GETTING_STARTED.md) for more advanced usage
2. **Try different templates**: Explore `python-web`, `python-cli`, or `python-data` templates
3. **Use with Claude Code**: The agents work seamlessly with Claude Code for AI-assisted development
4. **Customize**: Modify the Makefile and pyproject.toml to fit your needs

**Common next steps:**
- Add a CLI interface using `click` or `argparse`
- Set up GitHub Actions for CI/CD
- Add more comprehensive tests
- Create documentation with Sphinx
- Package and publish to PyPI

## Troubleshooting

**"kaizen-agentic: command not found"**
```bash
# Same install as Step 1 (Gitea extra index — see PACKAGE_RELEASE.md)
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/"
```

**"make: command not found"**
- On Windows: Install `make` via chocolatey or use the commands directly
- On macOS: Install via `brew install make`
- Alternative: Run commands directly (see Makefile for exact commands)

**Virtual environment issues**
```bash
# Remove and recreate
rm -rf .venv
make setup-python
```

**Import errors in tests**
```bash
# Make sure you're in the project root and virtual env is activated
source .venv/bin/activate
make test
```

## What You Learned

- ✅ How to install and use Kaizen Agentic
- ✅ Project initialization with templates
- ✅ Modern Python project structure
- ✅ Test-driven development workflow
- ✅ Code quality tools (linting, formatting, type checking)
- ✅ AI agents for development assistance
- ✅ Make-based development commands

You're now ready to build amazing Python projects with AI agent assistance! 🚀