From fbd2428d28bcd9191d28acf3bd1145d3916ca90a Mon Sep 17 00:00:00 2001 From: nullhack Date: Tue, 14 Apr 2026 06:25:53 -0400 Subject: [PATCH] docs: rewrite README for v3 workflow (3 roles, 6 steps, no setup_project.py) --- README.md | 304 +++++++++++++++++++----------------------------------- 1 file changed, 106 insertions(+), 198 deletions(-) diff --git a/README.md b/README.md index f467713..0d4318d 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,14 @@ [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url] -[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=for-the-badge)](docs/coverage/index.html) +[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=for-the-badge)](https://nullhack.github.io/python-project-template/coverage/) [![CI](https://img.shields.io/github/actions/workflow/status/nullhack/python-project-template/ci.yml?style=for-the-badge&label=CI)](https://github.com/nullhack/python-project-template/actions/workflows/ci.yml) [![Python](https://img.shields.io/badge/python-3.13-blue?style=for-the-badge)](https://www.python.org/downloads/) -> Python template with some awesome tools to quickstart any Python project +> Python template to quickstart any project with production-ready workflow, quality tooling, and AI-assisted development. -**πŸš€ Enterprise Python Project Template** - AI-enhanced development template with TDD workflows, quality standards, and zero-config tooling. - -## ⚑ Quick Start - -### Using This Template +## Quick Start ```bash # 1. Clone the template @@ -26,238 +22,150 @@ cd python-project-template # 2. Install UV package manager (if not installed) curl -LsSf https://astral.sh/uv/install.sh | sh -# 3. **IMPORTANT**: Customize the template for your project -python setup_project.py -# This interactive script will: -# - Rename directories from 'app' to your package name -# - Update pyproject.toml with your project details -# - Fix Docker configuration paths -# - Replace all template placeholders - -# 4. Follow the Git configuration commands shown by setup_project.py -# Example: git remote set-url origin https://github.com/yourname/yourproject - -# 5. Setup development environment +# 3. Set up the development environment uv venv && uv pip install -e '.[dev]' -# 6. Validate everything works -task test && task lint && task static-check +# 4. Customize template placeholders for your project +opencode && @setup-project -# 7. Initialize AI development environment (optional) -opencode && /init +# 5. Validate everything works +task test && task lint && task static-check && timeout 10s task run ``` -**⚠️ Template State Notice**: This project is currently in "template state" with placeholder values. The `setup_project.py` script **must** be run to properly configure Docker, package paths, and project metadata before development. - -**Requirements**: Python 3.13+ and UV package manager are required. +## What This Template Provides -## 🎯 What This Template Provides +### Development Workflow -This template creates a production-ready Python project with: +A **6-step Kanban workflow** with WIP=1 (one feature at a time), enforced by the filesystem: -### πŸ”§ **Project Setup & Customization** -- **Automated setup script** (`setup_project.py`) - Interactive customization with your project details -- **Smart folder renaming** - Automatically renames `app/` directory to match your project -- **Docker path fixing** - Updates Docker configuration to match your project structure -- **Git configuration** - Provides ready-to-use Git commands for remotes and user setup -- **Template processing** - Replaces all placeholders in pyproject.toml and configuration files - -### πŸ€– **AI-Enhanced Development Workflow** -- **Multi-session continuity** - Projects span multiple AI sessions with shared state in `TODO.md` -- **Specialized agents** - Built-in agents for architecture, development, QA, and repository management -- **Skills system** - Modular workflows for TDD, feature definition, prototyping, and releases - -### πŸ—οΈ **Enterprise Architecture & Quality** -- **SOLID principles** - Enforced through AI architecture reviews via OpenCode agents -- **Object Calisthenics** - Clean, behavior-rich code patterns enforced by QA workflows -- **100% test coverage** - TDD workflows with acceptance criteria docstrings and property-based testing (Hypothesis) -- **Mutation testing** - mutmut integration for test quality validation -- **Zero-config tooling** - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight pre-configured - -## πŸ€– AI-Powered Development +``` +docs/features/backlog/ ← features waiting to be worked on +docs/features/in-progress/ ← exactly one feature being built +docs/features/completed/ ← accepted and shipped features +``` -This project includes built-in AI agents to accelerate your development. +**3 roles, 6 steps:** -### Multi-Session Development +| Step | Role | What happens | +|------|------|-------------| +| 1. SCOPE | Product Owner | User stories + UUID acceptance criteria | +| 2. BOOTSTRAP + ARCH | Developer | Build system, module structure, ADRs | +| 3. TEST FIRST | Developer | Failing tests mapped 1:1 to UUID criteria | +| 4. IMPLEMENT | Developer | Redβ†’Greenβ†’Refactor, commit per green test | +| 5. VERIFY | Reviewer | Run all commands, code review, UUID traceability | +| 6. ACCEPT | Product Owner | Demo, validate, merge, tag | -Complex projects are developed across multiple AI sessions. `TODO.md` at the root acts as the shared state β€” any AI agent can pick up exactly where the last session stopped. +### AI Agents ```bash -# Start any session: read state, orient, continue -@developer /skill session-workflow - -# End any session: update TODO.md, commit progress, hand off -@developer /skill session-workflow +@product-owner # Defines features, picks from backlog, accepts deliveries +@developer # Architecture, tests, code, git, releases +@reviewer # Runs commands, reviews code β€” read+bash only +@setup-project # One-time template initialization ``` -### Feature Development Workflow +### Skills ```bash -# Define new features with SOLID principles -@developer /skill feature-definition - -# Create prototypes and validate concepts -@developer /skill prototype-script - -# Write comprehensive tests first (TDD) -@developer /skill tdd - -# Get architecture review before implementing -@architect - -# Implement with guided TDD workflow -@developer /skill implementation - -# Create releases with smart versioning -@repo-manager /skill git-release +/skill session-workflow # Read TODO.md, continue, hand off cleanly +/skill scope # Write user stories + acceptance criteria +/skill tdd # TDD: file naming, docstring format, markers +/skill implementation # Red-Green-Refactor, architecture, ADRs +/skill code-quality # ruff, pyright, coverage, complexity limits +/skill verify # Step 5 verification checklist +/skill pr-management # Branch naming, PR template, squash merge +/skill git-release # Hybrid calver versioning, themed naming +/skill create-skill # Add new skills to the system ``` -## πŸ—οΈ Architecture & Standards - -- **🎯 SOLID Principles** - Single responsibility, dependency inversion, clean interfaces -- **πŸ”§ Object Calisthenics** - No primitives, small classes, behavior-rich objects -- **πŸ§ͺ TDD Testing** - Acceptance criteria format with Given/When/Then docstrings, 100% coverage requirement -- **πŸ”¬ Property-Based Testing** - Hypothesis integration for robust edge case validation -- **🧬 Mutation Testing** - mutmut for genetic algorithm-based test quality assurance -- **⚑ Modern Toolchain** - UV, taskipy, Ruff, PyTest, Hypothesis, PyRight -- **πŸš€ Smart Releases** - Hybrid major.minor.calver versioning with AI-generated themed names - -## πŸ“‹ Development Commands - -This project uses **taskipy** for task automation (configured in `pyproject.toml`): +## Development Commands ```bash -# Core development workflow -task run # Execute version module (demo command) -task test # Run comprehensive test suite with coverage -task test-fast # Run fast tests only (skip slow tests) -task test-slow # Run only slow tests (marked with @pytest.mark.slow) -task lint # Format and lint code with ruff -task static-check # Type safety validation with pyright - -# Documentation -task doc-serve # Live pdoc documentation server (localhost:8080) -task doc-build # Build static pdoc API docs to docs/api/ -task doc-publish # Publish API docs to GitHub Pages - -# Quality assurance -task test-report # Detailed coverage report (included in task test) -task mut # Mutation testing with mutmut -task mut-clean # Reset mutation testing cache +task run # Run the application (humans) +timeout 10s task run # Run with timeout (agents β€” exit 124 = hung = FAIL) +task test # Full test suite with coverage report +task test-fast # Tests without coverage (faster iteration) +task test-slow # Only slow tests +task lint # ruff check + format +task static-check # pyright type checking +task doc-build # Generate API docs + coverage + test reports +task doc-publish # Publish unified docs site to GitHub Pages +task doc-serve # Live API doc server at localhost:8080 ``` -## 🐳 Docker Usage - -**⚠️ Important**: Run `python setup_project.py` first to configure the template before using Docker. - -Docker provides development environment with hot reload and integrated tooling: - -```bash -# Development environment with hot reload -docker-compose up # Main application (ports 8000, 8080, 5678) - -# Specialized services (use profiles) -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 your-project-name . # Build development image +## Code Quality Standards + +| Standard | Target | +|----------|--------| +| Coverage | 100% | +| Type checking | pyright, 0 errors | +| Linting | ruff, 0 issues, Google docstrings | +| Function length | ≀ 20 lines | +| Class length | ≀ 50 lines | +| Max nesting | 2 levels | +| Principles | YAGNI > KISS > DRY > SOLID > Object Calisthenics | + +## Test Conventions + +```python +def test__should_(): + """a1b2c3d4-e5f6-7890-abcd-ef1234567890: Short description ending with a period. + + Given: precondition + When: action + Then: single observable outcome + """ + # Given + ... + # When + ... + # Then + ... ``` -**Current Docker Configuration:** -- **Main service**: Hot reload development with volume mounts -- **Test profile**: Full test suite execution -- **Docs profile**: Live documentation server -- **Quality profile**: Linting and type checking - -**Note**: The Docker configuration currently references template paths and requires `setup_project.py` to be run for proper functionality. - +**Markers**: `@pytest.mark.unit` Β· `@pytest.mark.integration` Β· `@pytest.mark.slow` - -## πŸ”§ Technology Stack +## Technology Stack | Category | Tools | |----------|-------| -| **Package Management** | UV (blazing fast pip/poetry replacement) | -| **Task Automation** | taskipy (configured in pyproject.toml) | -| **Code Quality** | Ruff (linting + formatting), PyRight (type checking) | -| **Testing** | PyTest + Hypothesis (property-based testing), pytest-html (acceptance criteria reports) | -| **Mutation Testing** | mutmut (genetic algorithm-based mutation testing) | -| **Coverage** | pytest-cov (100% coverage requirement) | -| **AI Integration** | OpenCode agents and skills for development automation | -| **Documentation** | pdoc with search functionality and GitHub Pages publishing | -| **Containerization** | Docker development environment with hot reload and service profiles | - -## πŸ“ˆ Quality Metrics - -- βœ… **100% Test Coverage** - pytest-cov with fail-under=100 requirement -- βœ… **Static Type Safety** - PyRight type checking with full type hints -- βœ… **Zero Linting Issues** - Ruff automated formatting and Google-style conventions -- βœ… **Property-Based Testing** - Hypothesis integration for robust validation -- βœ… **Mutation Testing** - mutmut for genetic algorithm-based test quality validation -- βœ… **Acceptance Criteria Format** - Given/When/Then docstrings with pytest-html reporting -- βœ… **Architecture Compliance** - AI-enforced SOLID principles through OpenCode agents - -## πŸš€ Deployment Ready - -Projects generated from this template include Docker support for development: +| Package management | uv | +| Task automation | taskipy | +| Linting + formatting | Ruff | +| Type checking | PyRight | +| Testing | pytest + Hypothesis | +| Coverage | pytest-cov (100% required) | +| Documentation | pdoc + ghp-import | +| AI development | OpenCode agents + skills | -```bash -# After running setup_project.py in your configured project -docker build -t your-project-name . -docker run -p 8000:8000 your-project-name - -# Docker Compose development environment -docker-compose up # Development environment with hot reload -docker-compose --profile test up # Run test suite -docker-compose --profile docs up # Documentation server -docker-compose --profile quality up # Code quality checks - -# API documentation -task doc-build # Generates docs/api/index.html -task doc-serve # http://localhost:8080 (live server) -``` +## Documentation Site -## 🀝 Contributing +Published at [nullhack.github.io/python-project-template](https://nullhack.github.io/python-project-template): +- **API Reference** β€” pdoc-generated from source docstrings +- **Coverage Report** β€” line-by-line coverage breakdown +- **Test Results** β€” full pytest run results -Help improve this template for the entire Python community: +## Release Versioning -### Template Improvements +Format: `v{major}.{minor}.{YYYYMMDD}` -```bash -# Fork and improve the template -git clone https://github.com/your-username/python-project-template -cd python-project-template +Each release gets a unique **adjective-animal** name generated from the commit/PR content. -# Test your changes -python setup_project.py --dry-run --github-username testuser --yes +## Contributing -# Add new skills, agents, or template features -# Submit pull request with improvements +```bash +git clone https://github.com/nullhack/python-project-template +uv venv && uv pip install -e '.[dev]' +task test && task lint ``` -### Areas for Contribution -- **New Skills** - Add specialized workflows (deployment, security, performance) -- **Agent Enhancements** - Improve existing agents or add new specialized ones -- **Template Updates** - Better project structures, additional tooling, improved defaults -- **Documentation** - Usage guides, examples, best practices - -## πŸ“„ License - -Distributed under the MIT License. See [LICENSE](LICENSE) for details. - -## πŸ™ Built With +## License -- [Python Project Template](https://github.com/nullhack/python-project-template) - Enterprise-grade Python project template -- [OpenCode](https://opencode.ai) - AI-powered development platform -- [UV](https://astral.sh/uv/) - Modern Python package manager -- [Ruff](https://astral.sh/ruff/) - Extremely fast Python linter +MIT β€” see [LICENSE](LICENSE). --- -**Author:** eol ([@nullhack](https://github.com/nullhack)) -**Project:** [python-project-template](https://github.com/nullhack/python-project-template) +**Author:** eol ([@nullhack](https://github.com/nullhack)) **Documentation:** [nullhack.github.io/python-project-template](https://nullhack.github.io/python-project-template) @@ -270,4 +178,4 @@ Distributed under the MIT License. See [LICENSE](LICENSE) for details. [issues-shield]: https://img.shields.io/github/issues/nullhack/python-project-template.svg?style=for-the-badge [issues-url]: https://github.com/nullhack/python-project-template/issues [license-shield]: https://img.shields.io/badge/license-MIT-green?style=for-the-badge -[license-url]: https://github.com/nullhack/python-project-template/blob/main/LICENSE \ No newline at end of file +[license-url]: https://github.com/nullhack/python-project-template/blob/main/LICENSE