feat(project): create an ai-native paved road for python projects

Author: JonZeolla

.cursor/rules/python-template.mdc

@@ -0,0 +1,40 @@
+type: always
+
+---
+
+# AI-Native Python Paved Road Template Rules
+
+You are working on a cookiecutter template for generating modern Python projects.
+
+## Critical Context
+This is a TEMPLATE GENERATOR. Files in `{{cookiecutter.project_name}}/` contain Jinja2 variables that must be preserved exactly as written.
+
+## Tech Stack
+- Python 3.13+ with uv package manager (NOT pip/poetry)
+- pytest with >80% coverage requirement
+- Pre-commit: ruff, pyright, refurb
+- Security: grype, syft
+- CI/CD: GitHub Actions
+- Versioning: CalVer or SemVer-ish
+
+## Code Standards
+- Max line length: 120
+- Type hints required
+- Google-style docstrings
+- Use pathlib (no os.path)
+- Use logging (no print)
+- Specific exception handling
+
+## Key Commands
+```bash
+task init       # Setup environment
+task build      # Build project
+task test       # Run tests
+task lint       # Check code quality
+```
+
+## Template Testing
+```bash
+uvx cookiecutter .    # Generate project
+pytest tests/         # Test template
+```

.github/.grant.yml

@@ -0,0 +1,13 @@
+rules:
+  - pattern: "*"
+    name: "Block AGPL licenses"
+    mode: "block"
+    reason: "AGPL licenses are not allowed in this project"
+    licenses:
+      - "agpl"
+      - "agpl-1.0"
+      - "agpl-1.0-only"
+      - "agpl-1.0-or-later"
+      - "agpl-3.0"
+      - "agpl-3.0-only"
+      - "agpl-3.0-or-later"

.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Repository owner
+* @jonzeolla
+
+# Sensitive files (covers both the cookiecutter and generated files in the repo)
+.github/**  @jonzeolla
+LICENSE     @jonzeolla
+SECURITY.md @jonzeolla

.github/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size,
+visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not
+aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at
+<security@zenable.io>. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior
+was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those
+enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social
+media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private
+interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these
+terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or
+aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct [Mozilla CoC]:
+https://github.com/mozilla/diversity [FAQ]: https://www.contributor-covenant.org/faq [translations]: https://www.contributor-covenant.org/translations

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,9 @@
+# Summary of the issue
+
+## Expected behavior
+
+## Steps to reproduce
+
+## Your environment
+
+## Logs and error messages

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+# Contributor Comments
+
+## Pull Request Checklist
+
+Thank you for submitting a contribution!
+
+Please address the following items:
+
+- [ ] If you are adding a dependency, please explain how it was chosen.
+- [ ] If manual testing is needed in order to validate the changes, provide a testing plan and the expected results.
+- [ ] Validate that documentation is accurate and aligned to any project updates or additions.

.github/actions/bootstrap/action.yml

@@ -0,0 +1,85 @@
+---
+name: 'Bootstrap the repository'
+description: 'Sets up uv, adds Homebrew to PATH, installs Task, and initializes the repository'
+inputs:
+  token:
+    description: 'A Github token'
+    required: true
+  python-version:
+    description: 'Python version to use'
+    required: false
+    default: '3.13'
+  working-directory:
+    description: 'The working directory'
+    required: false
+    default: '.'
+runs:
+  using: 'composite'
+  steps:
+    - name: Create run_script for running scripts downstream
+      shell: 'bash --noprofile --norc -Eeuo pipefail {0}'
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        run_script="uv run --frozen"
+        echo "run_script=${run_script}" | tee -a "${GITHUB_ENV}"
+
+    - name: Setup uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+        cache-dependency-glob: "**/uv.lock"
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install Task
+      uses: arduino/setup-task@v2
+      with:
+        # Passing a repo token reduces the likelihood of API rate limit exceeded
+        repo-token: ${{ inputs.token }}
+
+    - name: Add Homebrew to the path
+      shell: 'bash --noprofile --norc -Eeuo pipefail {0}'
+      # This ensures compatibility with macOS runners and Linux runners with Homebrew
+      run: |
+        # Check if we're on macOS
+        if [[ "$RUNNER_OS" == "macOS" ]]; then
+          # macOS homebrew locations
+          if [[ -d "/opt/homebrew/bin" ]]; then
+            PATH="${PATH}:/opt/homebrew/bin"
+          elif [[ -d "/usr/local/bin" ]]; then
+            PATH="${PATH}:/usr/local/bin"
+          fi
+        else
+          # Linux homebrew location
+          if [[ -d "/home/linuxbrew/.linuxbrew/bin" ]]; then
+            PATH="${PATH}:/home/linuxbrew/.linuxbrew/bin"
+          fi
+        fi
+
+        export PATH
+        echo "PATH=${PATH}" | tee -a "${GITHUB_ENV}"
+
+        # Smoke test - don't fail if brew isn't available
+        if command -v brew &> /dev/null; then
+          echo "Homebrew found at: $(which brew)"
+          brew --version
+        else
+          echo "Homebrew not found, continuing without it"
+        fi
+      working-directory: ${{ inputs.working-directory }}
+
+    - name: Set Python hash for caching
+      shell: 'bash --noprofile --norc -Eeuo pipefail {0}'
+      run: |
+        # Create a hash of the Python version for better cache keys
+        echo "PY=$(python -VV | sha256sum | cut -d' ' -f1)" | tee -a "${GITHUB_ENV}"
+
+    - name: Cache pre-commit environments
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pre-commit
+        key: pre-commit|${{ env.PY }}|${{ hashFiles(format('{0}/.pre-commit-config.yaml', inputs.working-directory)) }}
+
+    - name: Initialize the repository
+      working-directory: ${{ inputs.working-directory }}
+      shell: 'bash --noprofile --norc -Eeuo pipefail {0}'
+      run: task -v init

.github/copilot-instructions.md

@@ -0,0 +1,89 @@
+# GitHub Copilot Instructions for AI-Native Python Paved Road
+
+You are working on a cookiecutter template for creating AI-native Python projects. This template provides a modern Python development setup with best practices
+built-in.
+
+## Context
+
+- This is a **template generator**, not a regular Python project
+- Files in `{{cookiecutter.project_name}}` directory contain Jinja2 template variables
+- The project uses `uv` as the package manager (not pip or poetry)
+- Python 3.13+ is the minimum requirement
+- The template uses python-semantic-release for automated versioning
+
+## Code Conventions
+
+1. **Imports**: Use absolute imports only
+2. **Type Hints**: Always include type hints for function parameters and return values
+3. **Docstrings**: Use Google-style docstrings for all public functions and classes
+4. **Error Handling**: Raise specific exceptions with descriptive messages
+5. **Path Handling**: Use pathlib.Path instead of os.path
+6. **Logging**: Use the logging module, never print()
+
+## File Patterns
+
+- `*.py`: Python source files
+- `*.toml`: Configuration files (pyproject.toml, etc.)
+- `*.yml`: GitHub Actions workflows
+- `*.md`: Documentation files
+- `*.j2`: Jinja2 templates (if any)
+
+## Testing Requirements
+
+- Write pytest tests for all new functionality, but run all tests with: `task test`
+- You can also run just unit tests with `task unit-test` and just integration tests with `task integration-test`
+- Use fixtures for test data setup and place it in `tests/conftest.py`
+- Maintain >80% code coverage
+- Mark tests appropriately: @pytest.mark.unit or @pytest.mark.integration
+
+## Task Automation
+
+Common tasks are automated via Taskfile:
+
+- `task init`: Initialize development environment
+- `task build`: Build the project
+- `task test`: Run all tests
+- `task lint`: Run code quality checks
+- `task clean`: Remove any build artifacts or temporary files
+
+## Security Considerations
+
+- Never hardcode secrets or credentials
+- Use environment variables for sensitive data
+- Follow OWASP secure coding practices
+- Run security scans with grype before releases
+
+## When Suggesting Code
+
+1. Check existing patterns in the codebase first
+2. Ensure compatibility with uv package manager
+3. Follow the established project structure
+4. Include appropriate error handling
+5. Add tests for new functionality
+6. Update documentation as needed
+
+## Template-Specific Guidelines
+
+When working with cookiecutter templates:
+
+- Preserve Jinja2 syntax in template files
+- Use proper escaping for template variables
+- Test template generation with various inputs
+- Ensure generated projects are functional
+
+## Common Patterns
+
+```python
+# Path handling
+from pathlib import Path
+project_root = Path(__file__).parent.parent
+
+# Logging setup
+import logging
+logger = logging.getLogger(__name__)
+
+# Type hints
+from typing import Optional, List, Dict
+def process_data(items: List[Dict[str, Any]]) -> Optional[str]:
+    ...
+```