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
│   ├── agent-claude-documentation.md
│   ├── agent-project-management.md
│   ├── agent-repository-structure.md
│   ├── agent-keepaTodofile.md
│   ├── agent-keepaChangelog.md
│   └── [other agent definitions]
├── .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:

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

1. **claude-expert** (`agent-claude-documentation.md`)
   - Specialized in Claude Code documentation and features
   - Access to official docs.claude.com resources
   - Handles Claude Code configuration and best practices

2. **project-assistant** (`agent-project-management.md`)
   - Project status tracking and progress management
   - Manages ProjectStatusDigest.md, ProjectDiary.md, and NEXT.md
   - Handles session start-up and wrap-up protocols

3. **repository-assistant** (`agent-repository-structure.md`)
   - Repository structure management and refactoring
   - Enforces directory structure conventions
   - Optimizes project organization

4. **todo-keeper** (`agent-keepaTodofile.md`)
   - Specialized Todo.md file management and maintenance
   - Task tracking, progress monitoring, and workflow optimization
   - Integrates todo management with issue tracking and TDD workflows

5. **changelog-keeper** (`agent-keepaChangelog.md`)
   - Specialized CHANGELOG.md file management and version history documentation
   - Semantic versioning and change categorization (Added, Changed, Fixed, etc.)
   - Integrates with release workflows and maintains Keep a Changelog format

6. **contributing-keeper** (`agent-keepaContributingfile.md`)
   - Specialized CONTRIBUTING.md file management and developer onboarding
   - Development workflow documentation and code standards maintenance
   - Contributor guidelines and community standards management

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

```bash
# Complete setup (recommended)
make setup-complete

# Activate environment
source .venv/bin/activate

# Verify installation
make test
```

### Alternative Setup Methods

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