diff --git a/README.md b/README.md index 364a61a..a0b6a08 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,10 @@ This project embraces the Japanese concept of "kaizen" (continuous improvement) pip install kaizen-agentic ``` -### Initialize a New Project +### Your First Project (New Users) +**👋 New to Kaizen Agentic?** Follow our [Hello World Tutorial](docs/HELLO_WORLD_TUTORIAL.md) for a complete step-by-step guide. + +### Create a Project (Experienced Users) ```bash # Create a new project with AI agents kaizen-agentic init my-project --template python-web @@ -30,7 +33,7 @@ make help # See all available commands cd your-existing-project # Install relevant agents -kaizen-agentic install todo-keeper changelog-keeper tdd-workflow +kaizen-agentic install keepaTodofile keepaChangelog tdd-workflow # Check what was installed kaizen-agentic status @@ -48,10 +51,10 @@ kaizen-agentic status ## Available Agents ### Project Management -- **todo-keeper**: Manages TODO.md files following Keep a Todofile format -- **changelog-keeper**: Maintains CHANGELOG.md files following Keep a Changelog format -- **contributing-keeper**: Creates and updates CONTRIBUTING.md files -- **project-assistant**: General project management and coordination +- **keepaTodofile**: Manages TODO.md files following Keep a Todofile format +- **keepaChangelog**: Maintains CHANGELOG.md files following Keep a Changelog format +- **keepaContributingfile**: Creates and updates CONTRIBUTING.md files +- **project-management**: General project management and coordination ### Development Process - **tdd-workflow**: Test-driven development workflow guidance @@ -60,13 +63,13 @@ kaizen-agentic status ### Code Quality - **code-refactoring**: Code improvement and refactoring guidance -- **agent-optimization**: Agent definition optimization and improvement +- **optimization**: Agent definition optimization and improvement - **datamodel-optimization**: Data model design and optimization ### Infrastructure -- **setup-repository**: Repository initialization and standards compliance +- **setupRepository**: Repository initialization and standards compliance - **claude-documentation**: Claude Code configuration and documentation -- **testing-efficiency**: Testing infrastructure optimization +- **tooling-optimization**: Repository tooling usage optimization [View complete agent list](docs/AGENT_DISTRIBUTION.md#agent-categories) diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index e87cc42..3998cf0 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -2,6 +2,8 @@ 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 @@ -50,9 +52,9 @@ cd my-project git init # Install agents -kaizen-agentic install setup-repository todo-keeper changelog-keeper +kaizen-agentic install setupRepository keepaTodofile keepaChangelog -# The setup-repository agent can create the full project structure +# The setupRepository agent can create the full project structure # Use it via Claude Code or manually follow its patterns ``` @@ -65,7 +67,7 @@ kaizen-agentic install setup-repository todo-keeper changelog-keeper cd /path/to/your/project # Install relevant agents -kaizen-agentic install todo-keeper changelog-keeper tdd-workflow +kaizen-agentic install keepaTodofile keepaChangelog tdd-workflow # Check what was installed kaizen-agentic status @@ -224,7 +226,7 @@ alias ka-list="kaizen-agentic list" # Now you can use: # ka status # ka update -# ka install todo-keeper +# ka install keepaTodofile ``` ## Language-Specific Integration @@ -295,7 +297,7 @@ kaizen-agentic status # Read agent files directly ls agents/ -cat agents/agent-todo-keeper.md +cat agents/agent-keepaTodofile.md # Validate your setup kaizen-agentic validate @@ -374,10 +376,10 @@ pip install kaizen-agentic **"No agents directory found"** ```bash # Install some agents first -kaizen-agentic install todo-keeper +kaizen-agentic install keepaTodofile # Or initialize a new project -kaizen-agentic init . --agents todo-keeper,changelog-keeper +kaizen-agentic init . --agents keepaTodofile,keepaChangelog ``` **"Agent validation fails"** diff --git a/docs/HELLO_WORLD_TUTORIAL.md b/docs/HELLO_WORLD_TUTORIAL.md new file mode 100644 index 0000000..58cc8c2 --- /dev/null +++ b/docs/HELLO_WORLD_TUTORIAL.md @@ -0,0 +1,270 @@ +# 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 + +```bash +pip install kaizen-agentic +``` + +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 +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** +```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! 🚀 \ No newline at end of file diff --git a/src/kaizen_agentic/installer.py b/src/kaizen_agentic/installer.py index 5e4ec8b..d4bd5ad 100644 --- a/src/kaizen_agentic/installer.py +++ b/src/kaizen_agentic/installer.py @@ -456,7 +456,7 @@ name = "{project_name}" version = "0.1.0" description = "A Python project with Kaizen Agentic agents" readme = "README.md" -requires-python = ">=3.8" +requires-python = ">=3.9" license = {{text = "MIT"}} authors = [ {{name = "Author Name", email = "author@example.com"}} @@ -479,14 +479,14 @@ where = ["src"] [tool.black] line-length = 88 -target-version = ['py38'] +target-version = ['py39'] [tool.flake8] max-line-length = 100 exclude = [".git", "__pycache__", "build", "dist"] [tool.mypy] -python_version = "3.8" +python_version = "3.9" warn_return_any = true warn_unused_configs = true disallow_untyped_defs = true