kaizen-agentic/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Kaizen Agentic is an AI agent development framework that embraces the Japanese concept of "kaizen" (continuous improvement). Every coding subagent becomes part of an optimization loop where performance is measured, patterns are analyzed, and specifications are refined over time.

Repository Structure

This is a modern Python project with agent development focus:

kaizen-agentic/
├── Makefile                    # Comprehensive development commands and workflows
├── pyproject.toml              # Python project configuration and dependencies
├── src/kaizen_agentic/         # Main Python package
│   ├── __init__.py            # Package exports and version info
│   ├── core.py                # Core Agent and AgentConfig classes
│   └── optimization.py        # OptimizationLoop and PerformanceMetrics
├── tests/                      # Test suite with pytest
│   ├── __init__.py
│   └── test_core.py           # Core functionality tests
├── agents/                     # Agent definitions and configurations (17 total)
│   ├── agent-claude-documentation.md
│   ├── agent-code-refactoring.md
│   ├── agent-datamodel-optimization.md
│   ├── agent-keepaChangelog.md
│   ├── agent-keepaContributingfile.md
│   ├── agent-keepaTodofile.md
│   ├── agent-optimization.md
│   ├── agent-priority-evaluation.md
│   ├── agent-project-management.md
│   ├── agent-releaseManager.md
│   ├── agent-requirements-engineering.md
│   ├── agent-setupRepository.md
│   ├── agent-tdd-workflow.md
│   ├── agent-test-maintenance.md
│   ├── agent-testing-efficiency.md
│   ├── agent-tooling-optimization.md
│   └── agent-wisdom-encouragement.md
├── .claude/                    # Claude Code configuration
│   └── settings.local.json    # Local permissions and settings
├── .venv/                     # Python virtual environment (created by setup)
├── TODO.md                    # Current todofile (Keep a Todofile format)
├── CHANGELOG.md               # Version history (Keep a Changelog format)
├── CONTRIBUTING.md            # Developer contribution guidelines
├── CLAUDE.md                  # Claude Code guidance documentation
├── LICENSE                    # MIT License
└── README.md                  # Project overview

Quick Start

For first-time setup or when starting fresh:

# Complete setup with development dependencies
make setup-complete

# Activate virtual environment
source .venv/bin/activate

# Verify everything works
make test && make lint

Key Development Commands

The Makefile provides an extensive set of commands for development workflow. Use make help to see all available commands.

Essential Commands

• make help - Show all available commands with descriptions
• make setup - Basic project setup (creates venv + installs package)
• make setup-complete - Complete setup including dev dependencies (recommended)
• make test - Run all tests with pytest
• make lint - Run code linting with flake8 (100 char line length)
• make format - Format code with black
• make clean - Clean build artifacts and cache

Environment Management

• make venv-status - Check virtual environment status
• make ensure-project-structure - Auto-create Python project structure if missing
• make install-dev - Install package in development mode
• make setup-dev - Install development dependencies (pytest, black, flake8, mypy)
• make install-deps - Install dependencies user-local (fallback option)
• make install-system - Install system dependencies via apt (requires sudo)

Testing Infrastructure

The project includes comprehensive testing capabilities:

Basic Testing

• make test - Run all tests with pytest
• make test-status - Show test status summary without re-running
• make test-new - Create new test file template
• make test-coverage ISSUE=X - Analyze test coverage for specific issue

Advanced Testing

• make test-clean - Clean test run (exclude workspaces, fresh cache)
• make test-tdd - Quick TDD tests for fast feedback (<30s)
• make test-changed - Run tests for changed files only
• make test-module MODULE=name - Run tests for specific module
• make test-efficient - Enhanced test suite excluding workspaces

Architectural Testing

• make test-arch - Run tests in architectural order (reverse dependency)
• make test-foundation - Foundation layer tests (fastest feedback)
• make test-infrastructure - Infrastructure layer tests
• make test-domain - Domain layer tests (business logic)
• make test-quick - Foundation + infrastructure only (fast)

Randomized Testing

• make test-random - Run tests in random order to detect hidden dependencies
• make test-random-seed SEED=X - Run with specific seed for reproducibility
• make test-random-repeat NUM=X - Run multiple random iterations

Issue Management

The project uses Gitea for issue tracking with integrated CLI tools:

• make issue-list - Show all issues with status and priority
• make issue-list-open - Show only open issues (active backlog)
• make issue-show ISSUE=X - Show detailed view of specific issue
• make issue-create TITLE='...' BODY='...' - Create new issue
• make issue-close ISSUE=X - Close an issue
• make issue-get - Export issues to various formats (CSV, JSON, TSV)

TDD Workflow

Complete test-driven development support:

• make tdd-start ISSUE=X - Start working on issue with requirements validation
• make tdd-add-test - Add test to current issue workspace
• make tdd-status - Show current workspace state
• make tdd-finish - Complete issue work (move tests to main)
• make test-from-issue ISSUE=X - Generate test skeleton from issue

Core Framework Architecture

The repository provides a working AI agent framework with kaizen optimization:

Core Classes

1. AgentConfig (src/kaizen_agentic/core.py)

   • Configuration dataclass for agents
   • Includes name, description, model, instructions, and metadata

2. Agent (src/kaizen_agentic/core.py)

   • Abstract base class for AI agents
   • Provides performance tracking and configuration updates
   • Implements kaizen optimization interface

3. OptimizationLoop (src/kaizen_agentic/optimization.py)

   • Implements continuous improvement cycles
   • Performance analysis and trend detection
   • Generates improvement recommendations

4. PerformanceMetrics (src/kaizen_agentic/optimization.py)

   • Container for agent performance data
   • Tracks execution time, success rate, quality scores

Agent System Architecture

Specialized agent definitions in agents/ directory (17 total):

Documentation & Claude Integration

1. claude-documentation (agent-claude-documentation.md)
   • Specialized assistant for Claude and Claude Code documentation, features, and best practices
   • Access to official docs.claude.com resources and Claude Code configuration

Project Management

2. project-management (agent-project-management.md)

   • Specialized assistant for project status, progress tracking, and development planning
   • Manages project coordination and workflow optimization

3. priority-evaluation (agent-priority-evaluation.md)

   • Specialized assistant to help evaluate and establish priorities for issues and tasks
   • Decision support and task prioritization

4. releaseManager (agent-releaseManager.md)

   • Manages software releases, version control, and publication workflows for Python packages
   • Handles semantic versioning and release automation

Documentation Keepers

5. keepaTodofile (agent-keepaTodofile.md)

   • Specialized assistant for maintaining TODO.md files following Keep a Todofile V0.0.1 format
   • Task tracking, progress monitoring, and workflow optimization

6. keepaChangelog (agent-keepaChangelog.md)

   • Specialized assistant for maintaining CHANGELOG.md files following Keep a Changelog format
   • Semantic versioning and change categorization

7. keepaContributingfile (agent-keepaContributingfile.md)

   • Specialized assistant for maintaining CONTRIBUTING.md files following Keep a Contributing-File V0.0.1 format
   • Developer onboarding and contribution guidelines

Development Process

8. tdd-workflow (agent-tdd-workflow.md)

   • Expert guidance for the TDD8 workflow methodology
   • ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle with sophisticated sidequest management

9. requirements-engineering (agent-requirements-engineering.md)

   • Specialized agent designed to prevent interface compatibility issues and mock object mismatches
   • Ensures solid foundation planning before implementation

Testing & Quality Assurance

10. test-maintenance (agent-test-maintenance.md)

    • Specialized agent for analyzing and fixing failing tests in the project
    • Test suite maintenance and optimization

11. testing-efficiency (agent-testing-efficiency.md)

    • Specialized agent designed to optimize TDD8 workflow test execution
    • Resolves pytest reliability issues and enhances testing efficiency

Code Quality & Optimization

12. code-refactoring (agent-code-refactoring.md)

    • Analyze code structure and quality, identify improvement opportunities
    • Provides actionable refactoring guidance (Use PROACTIVELY)

13. datamodel-optimization (agent-datamodel-optimization.md)

    • Systematically analyzes, optimizes, and enhances dataclasses, models, and data structures
    • Provides comprehensive datamodel improvements

14. optimization (agent-optimization.md)

    • Meta-agent that analyzes and optimizes other Claude Code subagents
    • Based on performance data, usage patterns, and effectiveness metrics (Use PROACTIVELY)

Infrastructure & Tooling

15. setupRepository (agent-setupRepository.md)

    • Specialized assistant for setting up new Python repositories following PythonVibes best practices
    • Repository initialization and standards compliance

16. tooling-optimization (agent-tooling-optimization.md)

    • Meta-agent that analyzes and optimizes repository tooling usage to improve development efficiency
    • Discovers and recommends better tool utilization

Support & Guidance

17. wisdom-encouragement (agent-wisdom-encouragement.md)
    • Provides encouraging wisdom and guidance for complex implementation tasks and challenging technical work
    • Fortune cookie-style wisdom for developers facing technical challenges

Development Workflow Patterns

Kaizen Philosophy

• Continuous Improvement: Every coding session should measure performance and refine specifications
• Pattern Recognition: Analyze agent behavior and optimize workflows over time
• Specification Evolution: Agent definitions should be updated based on performance data

Agent Optimization Loop

1. Measure: Track agent performance and effectiveness using PerformanceMetrics
2. Analyze: Use OptimizationLoop to identify patterns and trends
3. Refine: Update agent specifications and workflows based on insights
4. Iterate: Repeat the cycle for continuous improvement

Development Best Practices

1. Always use virtual environment: Run make venv-status before starting
2. Test-driven development: Write tests first, then implementation
3. Code quality: Run make lint and make format before commits
4. Performance tracking: Use the optimization framework for agent improvements
5. Todo tracking: Maintain a todofile for task management and progress tracking
6. Change documentation: Keep a changelog for version history and feature tracking

Python Project Configuration

Dependencies

Core Dependencies (pyproject.toml):

• pyyaml>=6.0 - YAML configuration parsing
• click>=8.0.0 - CLI framework
• pydantic>=2.0.0 - Data validation and settings

Development Dependencies:

• pytest>=6.0.0 - Testing framework
• black>=22.0.0 - Code formatting
• flake8>=5.0.0 - Code linting
• mypy>=1.0.0 - Type checking

Code Quality Configuration

• Black: Line length 88, Python 3.8+ target
• Flake8: Max line length 100, ignores E203, W503
• Pytest: Configured with markers for slow, integration, e2e, smoke tests
• MyPy: Strict typing with comprehensive checks enabled

Setup and Installation

First Time Setup

# Complete setup (recommended)
make setup-complete

# Activate environment
source .venv/bin/activate

# Verify installation
make test

Alternative Setup Methods

# Basic setup only
make setup

# Manual dev dependencies
make setup-dev

# Check environment status
make venv-status

Troubleshooting

If setup fails:

1. Try make install-system for system packages
2. Use make install-deps-force to override restrictions
3. Try make install-deps-venv for isolated environment

Project Management Tools

Todo Tracking

• Purpose: Maintain visibility into current tasks and progress
• File: TODO.md - Structured todofile following Keep a Todofile format
• Agent: Use todo-keeper agent for maintaining todofiles
• Usage: Track work items organized by impact type (Add, Refactor, Fix, Deprecate, Secure, Remove)
• Benefits: Helps maintain focus and provides clear progress indicators aligned with changelog categories
• Integration: Works well with issue management, TDD workflows, and changelog management
• Structure: Organized by change impact type, mirroring changelog categories
• Format: Uses markdown checkboxes within sprint-focused sections

Changelog Management

• Purpose: Document changes, features, and version history
• File: CHANGELOG.md - Structured markdown file following Keep a Changelog format
• Agent: Use changelog-keeper agent for maintaining CHANGELOG.md files
• Usage: Track what has been added, changed, fixed, removed, deprecated, or security-related
• Benefits: Provides clear communication about project evolution and version impacts
• Format: Follows Keep a Changelog standard with semantic versioning
• Structure: Organized by version with categories (Added, Changed, Fixed, Deprecated, Removed, Security)
• Integration: Links with git tags, releases, and issue references

Important Notes

• Self-healing setup: make setup automatically creates missing project structure
• Comprehensive help: Use make help to explore all available commands
• Agent-focused: Agent definitions in agents/ directory are the core of this system
• Quality-first: Always run tests and linting before commits
• TDD emphasis: The project emphasizes test-driven development workflows
• Kaizen approach: Apply continuous improvement principles to all development
• Documentation practices: Maintain todofiles and changelogs for better project management

Agent Usage Guidelines

When working with this repository:

1. Read Agent Definitions: Understand the specialized agents available in agents/
2. Follow TDD Patterns: Use the established test-driven development workflows
3. Measure and Improve: Apply kaizen principles using the optimization framework
4. Update Documentation: Keep agent definitions current with actual usage patterns
5. Use the Framework: Leverage the core Agent and OptimizationLoop classes for new agents
6. Test Everything: Use the comprehensive testing infrastructure for quality assurance
7. Track Progress: Maintain todofiles for current work and use changelog for completed work
8. Document Changes: Update changelog when adding features, fixing bugs, or making improvements
9. Version Management: Use changelog-keeper agent to maintain proper version history and semantic versioning