Skip to content

README.md

Latest commit

 

History

History
271 lines (203 loc) · 10.9 KB

README.md

File metadata and controls

271 lines (203 loc) · 10.9 KB

🚀 AI-Enhanced Python Project Template

Contributors Forks Stargazers Issues MIT License Coverage

CI Python

Ship production-ready Python projects faster with AI-powered development workflows

Current Version: v2.0.20260411 - Armored Pangolin

Modern Python template delivering enterprise-grade projects with OpenCode AI agents, TDD/BDD workflows, and intelligent development assistance.

✨ What You Get

🤖 Enterprise AI Development Team - 5 specialized agents: Developer, Architect, Business Analyst, QA Specialist, Release Engineer
🏗️ SOLID Architecture - Object Calisthenics, Dependency Inversion, Protocol-based design with architect review
🎯 Mandatory QA Gates - 4 quality checkpoints enforced by QA specialist throughout development
⚡ Modern Development - Fast uv package manager, pytest + Hypothesis testing, ruff linting
🔒 Security-First - CodeQL analysis, vulnerability scanning, and security-focused workflows
🔄 Smart Releases - Hybrid calver versioning with AI-generated themed names
📋 Epic-Based Workflow - Requirements-driven development with automatic feature progression
🛠️ Simple Setup - Clone, setup, OpenCode - start building immediately

🎯 Perfect For

  • Developers wanting AI-assisted development with modern tooling
  • Teams needing structured development workflows with quality gates
  • Projects requiring comprehensive testing and quality assurance
  • Startups wanting to build production-ready applications quickly
  • Anyone seeking a modern Python development experience

🚀 Quick Start

Simple 3-Step Setup

# 1. Clone the template
git clone https://github.com/nullhack/python-project-template.git your-project
cd your-project

# 2. Setup development environment (installs uv automatically if needed)
./setup.py  # Creates virtual environment and installs dependencies

# 3. Start AI-powered development
opencode

That's it! Your development environment is ready.

Start Building with AI Agents

# In OpenCode, gather requirements first
@requirements-gatherer  # Interviews stakeholders, analyzes needs

# Then start structured development 
@developer /skill epic-workflow start-epic "Your Feature Name"

# Or jump straight into feature development
@developer /skill feature-definition
@developer /skill tdd
@developer /skill implementation

🛠️ Development Workflow

Daily Commands

# Run your application
task run

# Test suite (fast tests + coverage)
task test

# Code quality checks
task lint              # Ruff linting and formatting
task static-check      # Type checking with pyright

# Documentation
task doc-serve         # Live documentation server
task doc-build         # Build static docs

# Development utilities
task test-fast         # Quick tests (skip slow ones)
task test-slow         # Integration tests only

Quality Assurance

The template enforces high standards automatically:

  • 100% Test Coverage - Comprehensive testing with pytest + hypothesis
  • Type Safety - Full type annotations with pyright checking
  • Code Quality - Ruff linting with security rules (flake8-bandit)
  • Security - CodeQL analysis and vulnerability scanning
  • Documentation - Auto-generated API docs with pdoc

🏛️ Architecture & Workflow

Epic-Based Development with Mandatory QA Gates

  1. Requirements Gathering → @requirements-gatherer conducts stakeholder interviews using BABOK methodology
  2. 🔒 QA Gate #1 → @overseer enforces requirements completeness review
  3. Test-Driven Development → @developer /skill tdd creates BDD-style tests with pytest + Hypothesis
  4. 🔒 QA Gate #2 → @overseer reviews test quality and coverage standards
  5. Design & Architecture → @architect ensures SOLID patterns and design review
  6. Implementation → @developer /skill implementation follows TDD Red-Green-Refactor cycle
  7. 🔒 QA Gate #3 → @overseer validates SOLID/DRY/KISS compliance
  8. Final Quality → @developer /skill code-quality runs comprehensive quality checks
  9. 🔒 QA Gate #4 → @overseer provides final approval before feature completion
  10. Automatic Progression → System advances to next feature in epic

🚫 Development cannot proceed without @overseer approval at each mandatory gate

Multi-Session Development State

Complex projects span multiple AI sessions using shared state management:

# Start any session: read TODO.md, understand current state, continue work
@developer /skill session-workflow

# End any session: update TODO.md, commit progress, hand off to next session  
@developer /skill session-workflow

🔧 Technology Stack

⚡ Modern Python Stack

  • UV package manager (5-10x faster than pip)
  • Python 3.13 with latest language features
  • Task automation with taskipy
  • Comprehensive testing with pytest + hypothesis

🤖 AI Development Team

  • @developer: TDD workflow implementation with QA integration
  • @architect: SOLID principles and design pattern enforcement
  • @requirements-gatherer: Business analysis using BABOK methodology
  • @overseer: Quality gates and mandatory checkpoint enforcement
  • @repo-manager: Release management and deployment workflows

⚡ Modern Python Stack

  • Python 3.13+ with advanced type hints and protocols
  • UV package manager (5-10x faster dependency management)
  • Ruff formatting and linting (replaces 8+ tools)
  • PyTest + Hypothesis for comprehensive testing

📊 Quality Assurance

  • 100% test coverage requirement with branch coverage
  • Property-based testing for edge case discovery
  • Static type checking with Pyright
  • Mutation testing with mutmut for test quality validation

📋 Development Commands

Native Development

# Core workflow
task run              # Execute main application
task test             # Complete test suite with coverage
task test-fast        # Fast tests (skip slow integration tests)
task lint             # Ruff formatting and linting
task static-check     # Pyright type checking
task doc-serve        # Live documentation server
task doc-build        # Static API documentation generation

Docker Development

# Development workflows
docker-compose up                     # Hot reload development environment
docker-compose --profile test up      # Run complete test suite
docker-compose --profile docs up      # Documentation server (localhost:8080)
docker-compose --profile quality up   # Code quality checks (lint + typecheck)

# Build standalone image
docker build -t python-template .     # Build development image

📈 Quality Metrics & Standards

  • ✅ 100% Test Coverage - Branch and line coverage with pytest-cov
  • ✅ Container Ready - Docker development environment with hot reload and debugging
  • ✅ Static Type Safety - Complete type hints with protocol-based interfaces
  • ✅ Zero Linting Issues - Automated Ruff formatting and style enforcement
  • ✅ Property-Based Testing - Hypothesis for robust edge case validation
  • ✅ Architecture Compliance - AI-enforced SOLID principles and Object Calisthenics
  • ✅ Development Friendly - Hot reload, debugging support, and integrated tooling

🚀 Release Management

Smart Versioning & Naming

  • Hybrid Calver: v{major}.{minor}.{YYYYMMDD} format
  • AI-Generated Names: Themed releases based on PR content analysis
    • Performance: "Swift Falcon" "Lightning Cheetah"
    • Security: "Guardian Shield" "Vigilant Owl"
    • Features: "Creative Fox" "Innovative Dolphin"
    • Infrastructure: "Solid Foundation" "Robust Castle"

Deployment Ready

# Build production-ready container
docker build --target production -t your-project:latest .
docker run your-project:latest

# Smart release with AI naming
@repo-manager /skill git-release
# Example: Creates v1.2.20260411 "Secure Fortress" (Docker security improvements)

# Run your application
docker-compose up --detach

🤝 Contributing

Help make this template the gold standard for Python development:

  • 🐛 Bug Reports & Fixes - Improve stability and reliability
  • ✨ New AI Agents & Skills - Expand development automation
  • 🐳 Container Optimizations - Enhance security and performance
  • 📚 Documentation - Help others succeed faster
  • 🎯 Workflow Improvements - Streamline development processes
# Quick contribution workflow
git clone https://github.com/nullhack/python-project-template.git
cd python-project-template
@developer /skill feature-definition    # Define your improvement
@developer /skill tdd                  # Test-driven implementation
@repo-manager /skill pr-management     # Professional PR creation

📄 License

MIT License - see LICENSE for details.

🙏 Built With Excellence

Standing on the shoulders of giants:

  • OpenCode - Revolutionary AI-powered development platform
  • UV - Blazing fast Python package and project manager
  • Ruff - Extremely fast Python linter and formatter
  • Docker - Containerization for development environment
  • Hypothesis - Property-based testing framework

⭐ Star this repo to power your next breakthrough project!