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

pip install kaizen-agentic

Verify the installation:

kaizen-agentic --version
kaizen-agentic list

You should see a list of available agents.

Step 2: Create Your First Project

# 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

# 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

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

# 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

# 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

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

# 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

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

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

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

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

pip install kaizen-agentic

"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

# Remove and recreate
rm -rf .venv
make setup-python

Import errors in tests

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