crackerjack 0.24.9__tar.gz → 0.25.0__tar.gz

{crackerjack-0.24.9 → crackerjack-0.25.0}/CLAUDE.md

@@ -16,6 +16,12 @@ pipx install uv
 
 # Install project dependencies
 uv sync
+
+# Run individual tools through UV (ensures proper environment isolation)
+uv run pytest
+uv run pyright
+uv run ruff check
+uv run pre-commit run --all-files
 ```
 
 ### Running Crackerjack
@@ -120,25 +126,34 @@ Crackerjack is designed with modern Python principles and consists of several ke
 1. **Crackerjack** (`crackerjack.py`): Main class that orchestrates the entire workflow
    - Manages configuration updates
    - Runs pre-commit hooks
-   - Handles code cleaning
-   - Executes tests
+   - Handles code cleaning (with enhanced error handling)
+   - Executes tests with dynamic parallelization
    - Manages version bumping and publishing
    - Handles Git operations
+   - Integrates with Rich console for status output
 
 2. **CodeCleaner**: Responsible for cleaning code
-   - Removes docstrings
+   - Removes docstrings (with syntax-aware pass statement insertion)
    - Removes line comments
    - Removes extra whitespace
    - Reformats code using Ruff
+   - Handles file encoding issues gracefully
 
 3. **ConfigManager**: Handles configuration file management
    - Updates pyproject.toml settings
    - Manages configuration files (.gitignore, .pre-commit-config.yaml)
+   - Supports dynamic configuration based on project size
 
 4. **ProjectManager**: Manages project-level operations
    - Runs pre-commit hooks
    - Updates package configurations
    - Runs interactive hooks
+   - Detects project size for optimization
+
+5. **ErrorHandler** (`errors.py`): Structured error handling system
+   - Provides consistent error codes and messages
+   - Handles graceful degradation on failures
+   - Supports both fatal and non-fatal error patterns
 
 ### Key Design Patterns
 
@@ -150,14 +165,15 @@ Crackerjack is designed with modern Python principles and consists of several ke
 
 Crackerjack has a robust testing setup with:
 
-- **Test Configuration**: Customizes pytest through conftest.py
-- **Benchmark Support**: Special handling for benchmark tests
+- **Test Configuration**: Customizes pytest through conftest.py with asyncio_mode="auto"
+- **Benchmark Support**: Special handling for benchmark tests (disabled in parallel execution)
 - **Smart Parallelization**: Adjusts the number of workers based on project size
 - **Project Size Detection**: Automatically detects project size to optimize test execution
-- **Timeout Protection**: Tests have dynamic timeouts based on project size
+- **Timeout Protection**: Tests have dynamic timeouts based on project size (default 300s)
 - **Deadlock Prevention**: Advanced threading techniques to prevent deadlocks
 - **Progress Tracking**: Shows periodic heartbeat messages for long-running tests
 - **AI Agent Integration**: Generates structured output files (JUnit XML, JSON coverage, benchmark JSON) when `--ai-agent` flag is used
+- **Async Testing**: Configured for asyncio-based tests with automatic mode detection
 
 ### Interactive Mode
 
@@ -181,6 +197,24 @@ The interactive mode runs a predefined workflow with tasks:
 
 Access interactive mode with: `python -m crackerjack -i`
 
+## Module Organization
+
+Crackerjack follows a single-file architecture for simplicity and maintainability:
+
+### File Structure
+- `crackerjack.py` - Main module (~3000 lines) containing all core functionality
+- `errors.py` - Structured error handling system
+- `interactive.py` - Rich-based interactive UI implementation
+- `py313.py` - Python 3.13+ specific feature detection
+- `__main__.py` - Entry point for `python -m crackerjack`
+
+### Key Implementation Details
+- **Single-file Design**: Most functionality concentrated in `crackerjack.py` for easier maintenance
+- **Type Safety**: Extensive use of protocols and type hints throughout
+- **Error Handling**: Comprehensive error handling with structured error codes
+- **Dynamic Configuration**: Project size detection affects worker count, timeouts, and other settings
+- **Rich Integration**: All console output uses Rich for enhanced terminal UI
+
 ## CLI Reference
 
 ### Core Options
@@ -218,22 +252,27 @@ Access interactive mode with: `python -m crackerjack -i`
 
 ## Development Guidelines
 
-1. **Code Style**: Follow the Crackerjack style guide:
+1. **Code Style**: Follow the Crackerjack style guide (see RULES.md):
    - **Target Python 3.13+** - Use latest Python features
-   - Use static typing throughout with modern syntax
+   - Use static typing throughout with modern syntax (import typing as `t`)
    - Use pathlib for file operations
    - Prefer Protocol over ABC
+   - Use built-in collection types (`list[str]`, `dict[str, int]`) instead of typing equivalents
    - Leverage Python 3.13+ performance and language improvements
 
 2. **Testing Approach**:
    - Write unit tests for all functionality
    - Add benchmark tests for performance-critical code
    - Tests are run in parallel by default
+   - **CRITICAL**: Use tempfile module for temporary files in tests (never create files directly on filesystem)
+   - Use pytest's `tmp_path` and `tmp_path_factory` fixtures
+   - Tests should be isolated and not affect the surrounding environment
 
 3. **Dependencies**:
-   - UV for dependency management
+   - UV for dependency management and tool execution
    - Ruff for linting and formatting
    - Pytest for testing
+   - All tools should be run through UV for environment isolation
 
 4. **Python Version**:
    - **Target: Python 3.13+** - Crackerjack requires Python 3.13 or newer

{crackerjack-0.24.9 → crackerjack-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crackerjack
-Version: 0.24.9
+Version: 0.25.0
 Summary: Crackerjack: code quality toolkit
 Project-URL: documentation, https://github.com/lesleslie/crackerjack
 Project-URL: homepage, https://github.com/lesleslie/crackerjack
@@ -595,19 +595,51 @@ Crackerjack is designed with modern Python principles in mind:
 
 ## Acknowledgments
 
--   **UV:** For excellent dependency and virtual environment management.
--   **Ruff:** For lightning-fast linting and code formatting.
--   **pre-commit:** For the robust hook management system.
--   **pytest:** For the flexible and powerful testing framework.
--   **PDM:** For the original inspiration for dependency management patterns.
--   **bandit:** For finding security vulnerabilities.
--   **vulture:** For dead code detection.
--   **creosote:** For unused dependency detection.
--   **complexipy:** For code complexity analysis.
--   **codespell:** For spelling correction.
--   **autotyping:** For automatically adding type hints.
--   **refurb:** For code improvement suggestions.
--   **pyright:** For static type checking.
--   **Typer:** For the creation of the CLI.
+Crackerjack stands on the shoulders of giants. We're grateful to the maintainers and contributors of these outstanding tools that make modern Python development possible:
+
+### Core Development Tools
+- **[UV](https://docs.astral.sh/uv/)** - Next-generation Python package and project management
+- **[Ruff](https://docs.astral.sh/ruff/)** - Lightning-fast Python linter and formatter written in Rust
+- **[pyright](https://microsoft.github.io/pyright/)** - Fast, feature-rich static type checker for Python
+- **[pytest](https://pytest.org/)** - Flexible and powerful testing framework
+
+### Code Quality & Security
+- **[pre-commit](https://pre-commit.com/)** - Multi-language pre-commit hooks framework
+- **[bandit](https://bandit.readthedocs.io/)** - Security vulnerability scanner for Python
+- **[vulture](https://github.com/jendrikseipp/vulture)** - Dead code detection tool
+- **[refurb](https://github.com/dosisod/refurb)** - Code modernization and improvement suggestions
+- **[codespell](https://github.com/codespell-project/codespell)** - Spelling mistake detection and correction
+- **[detect-secrets](https://github.com/Yelp/detect-secrets)** - Prevention of secrets in repositories
+
+### Dependencies & Project Management
+- **[creosote](https://github.com/fredrikaverpil/creosote)** - Unused dependency detection
+- **[autotyping](https://github.com/JelleZijlstra/autotyping)** - Automatic type hint generation
+- **[complexipy](https://github.com/rohaquinlop/complexipy)** - Code complexity analysis
+
+### CLI & User Interface
+- **[Typer](https://typer.tiangolo.com/)** - Modern CLI framework for building command-line interfaces
+- **[Rich](https://rich.readthedocs.io/)** - Rich text and beautiful formatting in the terminal
+- **[click](https://click.palletsprojects.com/)** - Python package for creating command line interfaces
+
+### Performance & Development Tools
+- **[icecream](https://github.com/gruns/icecream)** - Sweet and creamy print debugging
+- **[bevy](https://github.com/ZeroIntensity/bevy)** - Lightweight dependency injection framework
+- **[msgspec](https://github.com/jcrist/msgspec)** - High-performance message serialization
+- **[attrs](https://github.com/python-attrs/attrs)** - Classes without boilerplate
+
+### Development Environment
+- **[PyCharm](https://www.jetbrains.com/pycharm/)** - The premier Python IDE that powered the development of Crackerjack
+- **[Claude Code](https://claude.ai/code)** - AI-powered development assistant that accelerated development and ensured code quality
+
+### Legacy Inspiration
+- **[PDM](https://pdm.fming.dev/)** - Original inspiration for modern Python dependency management patterns
+
+### Special Recognition
+
+We extend special thanks to the **Astral team** for their groundbreaking work on UV and Ruff, which have revolutionized Python tooling. Their commitment to performance, reliability, and developer experience has set new standards for the Python ecosystem.
+
+The integration of these tools into Crackerjack's unified workflow demonstrates the power of the modern Python toolchain when thoughtfully combined. Each tool excels in its domain, and together they create a development experience that is both powerful and delightful.
+
+We're honored to build upon this foundation and contribute to the Python community's continued evolution toward better development practices and tools.
 
 ---

{crackerjack-0.24.9 → crackerjack-0.25.0}/README.md

@@ -551,19 +551,51 @@ Crackerjack is designed with modern Python principles in mind:
 
 ## Acknowledgments
 
--   **UV:** For excellent dependency and virtual environment management.
--   **Ruff:** For lightning-fast linting and code formatting.
--   **pre-commit:** For the robust hook management system.
--   **pytest:** For the flexible and powerful testing framework.
--   **PDM:** For the original inspiration for dependency management patterns.
--   **bandit:** For finding security vulnerabilities.
--   **vulture:** For dead code detection.
--   **creosote:** For unused dependency detection.
--   **complexipy:** For code complexity analysis.
--   **codespell:** For spelling correction.
--   **autotyping:** For automatically adding type hints.
--   **refurb:** For code improvement suggestions.
--   **pyright:** For static type checking.
--   **Typer:** For the creation of the CLI.
+Crackerjack stands on the shoulders of giants. We're grateful to the maintainers and contributors of these outstanding tools that make modern Python development possible:
+
+### Core Development Tools
+- **[UV](https://docs.astral.sh/uv/)** - Next-generation Python package and project management
+- **[Ruff](https://docs.astral.sh/ruff/)** - Lightning-fast Python linter and formatter written in Rust
+- **[pyright](https://microsoft.github.io/pyright/)** - Fast, feature-rich static type checker for Python
+- **[pytest](https://pytest.org/)** - Flexible and powerful testing framework
+
+### Code Quality & Security
+- **[pre-commit](https://pre-commit.com/)** - Multi-language pre-commit hooks framework
+- **[bandit](https://bandit.readthedocs.io/)** - Security vulnerability scanner for Python
+- **[vulture](https://github.com/jendrikseipp/vulture)** - Dead code detection tool
+- **[refurb](https://github.com/dosisod/refurb)** - Code modernization and improvement suggestions
+- **[codespell](https://github.com/codespell-project/codespell)** - Spelling mistake detection and correction
+- **[detect-secrets](https://github.com/Yelp/detect-secrets)** - Prevention of secrets in repositories
+
+### Dependencies & Project Management
+- **[creosote](https://github.com/fredrikaverpil/creosote)** - Unused dependency detection
+- **[autotyping](https://github.com/JelleZijlstra/autotyping)** - Automatic type hint generation
+- **[complexipy](https://github.com/rohaquinlop/complexipy)** - Code complexity analysis
+
+### CLI & User Interface
+- **[Typer](https://typer.tiangolo.com/)** - Modern CLI framework for building command-line interfaces
+- **[Rich](https://rich.readthedocs.io/)** - Rich text and beautiful formatting in the terminal
+- **[click](https://click.palletsprojects.com/)** - Python package for creating command line interfaces
+
+### Performance & Development Tools
+- **[icecream](https://github.com/gruns/icecream)** - Sweet and creamy print debugging
+- **[bevy](https://github.com/ZeroIntensity/bevy)** - Lightweight dependency injection framework
+- **[msgspec](https://github.com/jcrist/msgspec)** - High-performance message serialization
+- **[attrs](https://github.com/python-attrs/attrs)** - Classes without boilerplate
+
+### Development Environment
+- **[PyCharm](https://www.jetbrains.com/pycharm/)** - The premier Python IDE that powered the development of Crackerjack
+- **[Claude Code](https://claude.ai/code)** - AI-powered development assistant that accelerated development and ensured code quality
+
+### Legacy Inspiration
+- **[PDM](https://pdm.fming.dev/)** - Original inspiration for modern Python dependency management patterns
+
+### Special Recognition
+
+We extend special thanks to the **Astral team** for their groundbreaking work on UV and Ruff, which have revolutionized Python tooling. Their commitment to performance, reliability, and developer experience has set new standards for the Python ecosystem.
+
+The integration of these tools into Crackerjack's unified workflow demonstrates the power of the modern Python toolchain when thoughtfully combined. Each tool excels in its domain, and together they create a development experience that is both powerful and delightful.
+
+We're honored to build upon this foundation and contribute to the Python community's continued evolution toward better development practices and tools.
 
 ---

{crackerjack-0.24.9 → crackerjack-0.25.0}/crackerjack/crackerjack.py

@@ -634,7 +634,7 @@ class CodeCleaner(BaseModel, arbitrary_types_allowed=True):
                 temp_path.write_text(code)
             try:
                 result = subprocess.run(
-                    ["ruff", "format", str(temp_path)],
+                    ["uv", "run", "ruff", "format", str(temp_path)],
                     check=False,
                     capture_output=True,
                     text=True,
@@ -887,7 +887,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
             self.execute_command(["git", "branch", "-m", "main"])
             self.execute_command(["git", "add", "pyproject.toml", "uv.lock"])
             self.execute_command(["git", "config", "advice.addIgnoredFile", "false"])
-            install_cmd = ["pre-commit", "install"]
+            install_cmd = ["uv", "run", "pre-commit", "install"]
             if hasattr(self, "options") and getattr(self.options, "ai_agent", False):
                 install_cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
             self.execute_command(install_cmd)
@@ -899,7 +899,7 @@ class ProjectManager(BaseModel, arbitrary_types_allowed=True):
             "[bold bright_cyan]🔍 HOOKS[/bold bright_cyan] [bold bright_white]Running code quality checks[/bold bright_white]"
         )
         self.console.print("-" * 60 + "\n")
-        cmd = ["pre-commit", "run", "--all-files"]
+        cmd = ["uv", "run", "pre-commit", "run", "--all-files"]
         if hasattr(self, "options") and getattr(self.options, "ai_agent", False):
             cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
         check_all = self.execute_command(cmd)
@@ -990,7 +990,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
 
     def _update_precommit(self, options: t.Any) -> None:
         if self.pkg_path.stem == "crackerjack" and options.update_precommit:
-            update_cmd = ["pre-commit", "autoupdate"]
+            update_cmd = ["uv", "run", "pre-commit", "autoupdate"]
             if options.ai_agent:
                 update_cmd.extend(["-c", ".pre-commit-config-ai.yaml"])
             self.execute_command(update_cmd)
@@ -1076,7 +1076,7 @@ class Crackerjack(BaseModel, arbitrary_types_allowed=True):
             test.append("-xvs")
 
     def _prepare_pytest_command(self, options: OptionsProtocol) -> list[str]:
-        test = ["pytest"]
+        test = ["uv", "run", "pytest"]
         project_size = self._detect_project_size()
         test_timeout = self._get_test_timeout(options, project_size)
         if getattr(options, "ai_agent", False):

{crackerjack-0.24.9 → crackerjack-0.25.0/crackerjack}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "crackerjack"
-version = "0.24.9"
+version = "0.24.10"
 description = "Crackerjack: code quality toolkit"
 readme = "README.md"
 keywords = [

{crackerjack-0.24.9/crackerjack → crackerjack-0.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "crackerjack"
-version = "0.24.8"
+version = "0.25.0"
 description = "Crackerjack: code quality toolkit"
 readme = "README.md"
 keywords = [

{crackerjack-0.24.9 → crackerjack-0.25.0}/tests/test_crackerjack.py

@@ -909,7 +909,9 @@ class TestCrackerjackProcess:
             with patch.object(cj, "_setup_package"):
                 with patch.object(cj, "_update_project"):
                     cj.process(options)
-                    mock_cj_execute.assert_any_call(["pre-commit", "autoupdate"])
+                    mock_cj_execute.assert_any_call(
+                        ["uv", "run", "pre-commit", "autoupdate"]
+                    )
 
     def test_update_precommit_ai_agent(
         self,
@@ -927,7 +929,14 @@ class TestCrackerjackProcess:
                 with patch.object(cj, "_update_project"):
                     cj.process(options)
                     mock_cj_execute.assert_any_call(
-                        ["pre-commit", "autoupdate", "-c", ".pre-commit-config-ai.yaml"]
+                        [
+                            "uv",
+                            "run",
+                            "pre-commit",
+                            "autoupdate",
+                            "-c",
+                            ".pre-commit-config-ai.yaml",
+                        ]
                     )
 
     def test_run_pre_commit_ai_agent(
@@ -943,7 +952,15 @@ class TestCrackerjackProcess:
         mock_project.execute_command.return_value = MagicMock(returncode=0)
         ProjectManager.run_pre_commit(mock_project)
         mock_project.execute_command.assert_called_with(
-            ["pre-commit", "run", "--all-files", "-c", ".pre-commit-config-ai.yaml"]
+            [
+                "uv",
+                "run",
+                "pre-commit",
+                "run",
+                "--all-files",
+                "-c",
+                ".pre-commit-config-ai.yaml",
+            ]
         )
 
     def test_pre_commit_install_ai_agent(
@@ -965,7 +982,14 @@ class TestCrackerjackProcess:
             original_method = ProjectManager.update_pkg_configs
             original_method(mock_project)
             mock_execute.assert_any_call(
-                ["pre-commit", "install", "-c", ".pre-commit-config-ai.yaml"]
+                [
+                    "uv",
+                    "run",
+                    "pre-commit",
+                    "install",
+                    "-c",
+                    ".pre-commit-config-ai.yaml",
+                ]
             )
 
     def test_process_with_precommit_failure(

{crackerjack-0.24.9 → crackerjack-0.25.0}/uv.lock

@@ -105,7 +105,7 @@ wheels = [
 
 [[package]]
 name = "crackerjack"
-version = "0.24.9"
+version = "0.25.0"
 source = { editable = "." }
 dependencies = [
     { name = "autotyping" },

crackerjack-0.24.9/.windsurfrules

@@ -1,188 +0,0 @@
-# Windsurf AI Rules for Crackerjack Projects
-
-## Project Context
-This is a Crackerjack project - an opinionated Python project management tool that streamlines development workflow by combining best-in-class tools. When working on this codebase or projects that use Crackerjack, follow these rules strictly.
-
-## Code Quality & Style
-
-### Static Typing Requirements
-- Always include comprehensive type hints for all functions, methods, and variables
-- Import typing as `import typing as t` and prefix all typing references with `t.`
-- Never import individual types directly from typing (avoid `from typing import List, Dict, Optional`)
-- Use modern typing syntax with pipe operator (`|`) for unions instead of `Optional[T]`
-- Use built-in collection types: `list[str]` not `t.List[str]`, `dict[str, int]` not `t.Dict[str, int]`
-- Use `t.Protocol` instead of abstract base classes
-- Apply `@t.runtime_checkable` decorator to protocols when runtime checking is needed
-
-### Modern Python Standards
-- Target Python 3.13+ features and syntax exclusively
-- Use f-strings for all string formatting
-- Prefer `pathlib.Path` over `os.path` for file operations
-- Use dataclasses for structured data
-- Adopt latest language features immediately
-
-### Code Architecture
-- Write modular functions that do one thing well
-- Avoid unnecessary docstrings and line comments unless they explain "why" not "what"
-- Choose clear, descriptive variable and function names
-- Group related functionality into well-defined classes
-- Structure projects with clear separation of concerns
-
-## Tool Integration & Commands
-
-### PDM Usage
-- Always use `pdm run` to execute tools within the project's virtual environment
-- Run pytest with `pdm run pytest` instead of calling pytest directly
-- Execute all tools through PDM: `pdm run pyright`, `pdm run ruff`, `pdm run crackerjack`
-- Install dependencies with `pdm install`
-
-### Crackerjack Commands
-- Run basic process: `python -m crackerjack`
-- Clean, test, and commit: `python -m crackerjack -x -t -c`
-- Auto bump and commit: `python -m crackerjack -a micro`
-- Interactive mode: `python -m crackerjack -i`
-- Test only: `python -m crackerjack -t`
-- Skip pre-commit during testing: `python -m crackerjack -t -s`
-- Optimize for large projects: `python -m crackerjack -t --test-workers=2 --test-timeout=300`
-
-### Quality Validation
-- Code is incomplete until it passes: `python -m crackerjack -x -t`
-- This validates typing, formatting, linting, and test success
-- Run `pre-commit run --all-files` during development
-- All code must pass pre-commit checks before submission
-
-## Testing Standards
-
-### Test Environment
-- Use pytest with asyncio_mode="auto" for async testing
-- Never create files directly on filesystem in tests
-- Always use `tempfile` module or pytest's `tmp_path` fixtures
-- Tests must be isolated and not affect surrounding environment
-- Avoid hard-coded paths pointing to real filesystem
-
-### Test Configuration
-- Write tests for behavior, not implementation details
-- Focus on testing public interfaces rather than private functions
-- Use parallel test execution when appropriate
-- Add timeouts to prevent hanging tests
-- Separate unit tests, integration tests, and benchmarks
-- Aim for complete coverage of critical paths
-
-### Benchmark Testing
-- Run benchmarks: `python -m crackerjack -t --benchmark`
-- Regression detection: `python -m crackerjack -t --benchmark-regression`
-- Custom threshold: `python -m crackerjack -t --benchmark-regression --benchmark-regression-threshold=10.0`
-
-## Error Handling & Output
-
-### Exception Management
-- Use structured exception handling with specific exception types
-- Provide meaningful error messages with context
-- Handle errors gracefully and provide actionable feedback
-
-### Console Output
-- Use Rich library for all console output
-- Provide clear status indicators for operations
-- Format output for readability and user experience
-
-## Development Workflow
-
-### Pre-commit Hooks
-Configure comprehensive pre-commit hooks:
-- Pyright for static type checking
-- Ruff for linting and formatting
-- Vulture for detecting unused code
-- Creosote for identifying large files
-- Flynt for string formatting conversion
-- Codespell for spell checking
-- Autotyping for type annotation
-- Refurb for Python code modernization
-- Bandit for security vulnerabilities
-
-### Version Management
-- Use semantic versioning
-- Bump versions through Crackerjack: `-b micro|minor|major`
-- Publish to PyPI: `-p micro|minor|major`
-- Version bumping handled through PDM
-
-### Git Operations
-- Commit after pre-commit: `python -m crackerjack -c`
-- Create pull requests: `python -m crackerjack -r`
-- Never commit changes unless explicitly requested
-
-## Dependency Management
-
-### Package Management
-- Use PDM with uv for dependency management
-- Keep external dependencies minimal
-- Pin exact versions in lockfiles
-- Use range specifications in pyproject.toml
-- Regularly audit dependencies for security
-- Prefer standard library solutions when reasonable
-
-### Configuration
-- Use pyproject.toml for all project configuration
-- Follow standard package layout conventions
-- Configure all tools through pyproject.toml when possible
-
-## Performance & Optimization
-
-### Code Performance
-- Use profiling tools for critical code paths
-- Benchmark alternative implementations
-- Favor readability over micro-optimizations
-- Document non-obvious optimizations with rationale
-
-### Test Performance
-- Adjust test workers based on project size
-- Use appropriate timeouts for test execution
-- Implement deadlock prevention for threading
-- Show progress tracking for long-running tests
-
-## Documentation Philosophy
-
-### Minimalist Approach
-- Focus documentation on "why" rather than "what"
-- Document APIs at module/class level, not individual functions
-- Use type hints to replace parameter documentation
-- Create examples for complex functionality
-- Avoid verbose explanations
-
-## Security & Best Practices
-
-### Security Standards
-- Never expose or log secrets and keys
-- Never commit secrets to repository
-- Use Bandit for security vulnerability scanning
-- Follow security best practices consistently
-
-### Code Review
-- All code must be reviewed before merging
-- Automate style checks to focus reviews on substance
-- Look for edge cases and error handling
-- Ensure tests adequately cover changes
-
-## Project-Specific Guidelines
-
-### For Crackerjack Core Development
-- Maintain the opinionated nature of the tool
-- Enforce single correct way to accomplish tasks
-- Remove unnecessary flexibility that leads to inconsistency
-- Value clarity over brevity
-
-### For Projects Using Crackerjack
-- Follow all Crackerjack style rules
-- Use Crackerjack for all development workflow tasks
-- Configure projects to pass `python -m crackerjack -x -t`
-- Adopt Crackerjack's opinionated choices consistently
-
-## AI Assistant Instructions
-
-When working on Crackerjack or projects using Crackerjack:
-1. Always check code against these rules before suggesting changes
-2. Run appropriate Crackerjack commands to validate changes
-3. Ensure all code follows the typing and style guidelines
-4. Use PDM for all tool execution
-5. Test changes thoroughly with appropriate timeouts
-6. Never compromise on code quality standards
-7. Maintain the opinionated, high-quality nature of the project