Restructure contribution documentation and add formatter templates

Break down the monolithic CONTRIBUTING.md into focused files in docs/contributing/,
eliminate duplicated information, and add templates for new formatter development.

The new structure provides clearer separation of concerns and removes redundancy
while adding practical templates and examples for contributors.

Assisted-by: Opencode (GLM-4.6)

Author: henriquemoody

AGENTS.md

@@ -0,0 +1,53 @@
+# Agent Instructions
+
+This file contains instructions for AI agents working on this repository.
+
+## Development Commands
+
+| Command            | Description                      |
+| ------------------ | -------------------------------- |
+| `composer install` | Install dependencies             |
+| `composer test`    | Run all tests                    |
+| `composer lint`    | Check PSR-12 compliance          |
+| `composer format`  | Fix coding style automatically   |
+| `composer analyze` | Run static analysis with PHPStan |
+
+## Testing & Quality Standards
+
+- **Unit tests**: Located in `tests/Unit/`
+- **All contributions must include tests that pass**
+- **Code style**: Follow PSR-12 coding standard
+- **Static analysis**: Use PHPStan, fix any issues before submitting
+
+## Formatter Development
+
+When creating new formatters:
+
+1. **Class template**: `docs/contributing/templates/php/src/TemplateFormatter.php`
+2. **Test template**: `docs/contributing/templates/php/tests/TemplateFormatterTest.php`  
+3. **Documentation template**: `docs/contributing/templates/formatter-documentation-template.md`
+
+All formatters must implement the `Respect\StringFormatter\Formatter` interface.
+
+## Commit Guidelines
+
+Follow the detailed rules in `docs/contributing/commit-guidelines.md`:
+- Title: 5-116 characters, imperative mood, starts with capital
+- Body: Explain WHY, max 116 characters per line
+- Footer: Use trailers for references and AI attribution
+
+## Repository Structure
+
+- `/src/` - Formatter implementations
+- `/tests/Unit/` - Unit tests
+- `/docs/` - Documentation including formatter docs
+- `/docs/contributing/` - Contribution guidelines and templates
+
+## Before Submitting Changes
+
+1. Run composer commands: `test`, `lint`, `analyze`
+2. Ensure documentation follows templates
+3. Check commit message follows guidelines
+4. Verify all tests pass
+
+Remember: Reference external docs rather than duplicating information in this file.

CONTRIBUTING.md

@@ -1,199 +1,14 @@
 # Contributing to StringFormatter
 
-Thank you for considering contributing to StringFormatter! This document provides guidelines and information for contributors.
+Thank you for considering contributing to StringFormatter! This document provides an overview of the contribution process.
 
-## Getting Started
+For detailed guidelines, see the [contributing documentation](docs/contributing/):
 
-### Prerequisites
-
-- PHP 8.5 or higher
-- Composer
-- Git
-
-### Setting Up the Development Environment
-
-1. **Fork the repository**
-
-```bash
-# Fork the repository on GitHub, then clone your fork
-git clone https://github.com/yourusername/StringFormatter.git
-cd StringFormatter
-```
-
-2. **Install dependencies**
-
-```bash
-composer install
-```
-
-3. **Run tests**
-
-```bash
-composer test
-```
-
-## How to Contribute
-
-### Adding New Formatters
-
-StringFormatter is designed to be extensible. All formatters must implement the `Respect\StringFormatter\Formatter` interface.
-
-**Steps to add a new formatter:**
-
-1. **Create the formatter class**
-
-```php
-<?php
-
-declare(strict_types=1);
-
-namespace Respect\StringFormatter;
-
-final readonly class YourFormatter implements Formatter
-{
-    public function format(string $input): string
-    {
-        // Your formatting implementation
-        return $formattedInput;
-    }
-}
-```
-
-2. **Create tests**
-
-```php
-<?php
-// tests/Unit/YourFormatterTest.php
-
-declare(strict_types=1);
-
-namespace Respect\StringFormatter\Test\Unit;
-
-use PHPUnit\Framework\TestCase;
-use Respect\StringFormatter\YourFormatter;
-
-final class YourFormatterTest extends TestCase
-{
-    // Test your formatter implementation
-}
-```
-
-3. **Add documentation**
-   - Create `docs/YourFormatter.md` following the template used by MaskFormatter
-   - Include usage examples, API reference, and any special considerations
-
-4. **Update README.md**
-   - Add your formatter to the "Formatters" table
-
-### Testing
-
-- **Unit tests**: Located in `tests/Unit/`
-- **Run all tests**: `composer test`
-
-All contributions must include tests that pass.
-
-### Code Style
-
-This project follows the PSR-12 coding standard via the Respect Coding Standard. Run the following command before submitting:
-
-```bash
-composer lint  # Check coding style
-composer format # Fix coding style automatically
-```
-
-### Static Analysis
-
-This project uses PHPStan for static analysis. Run:
-
-```bash
-composer analyze  # Run static analysis
-```
-
-### Submitting Changes
-
-1. **Create a feature branch**
-
-```bash
-git checkout -b feature/your-feature-name
-```
-
-2. **Make your changes**
-   - Add your formatter implementation
-   - Include comprehensive tests
-   - Update documentation
-   - Follow PSR-12 coding standards
-
-3. **Test your changes**
-
-```bash
-composer test    # Run tests
-composer lint     # Check code style
-composer format   # Fix coding style automatically
-composer analyze  # Run static analysis
-```
-
-4. **Commit your changes**
-
-```bash
-git add .
-git commit -m "Add YourFormatter for [purpose]"
-```
-
-5. **Push and create a pull request**
-
-```bash
-git push origin feature/your-feature-name
-```
-
-Then create a pull request on GitHub with:
-
-- Clear description of the changes
-- Link to any relevant issues
-- Explain the use case and benefits
-
-## Development Commands
-
-| Command            | Description                      |
-| ------------------ | -------------------------------- |
-| `composer install` | Install dependencies             |
-| `composer test`    | Run all tests                    |
-| `composer lint`    | Check PSR-12 compliance          |
-| `composer format`  | Fix coding style automatically   |
-| `composer analyze` | Run static analysis with PHPStan |
-
-## Guidelines
-
-### Do
-
-- Write clear, well-documented code
-- Include comprehensive tests
-- Follow PSR-12 coding standards
-- Use type declarations everywhere
-- Write commit messages that explain the "why" not just the "what"
-
-### Don't
-
-- Submit changes without tests
-- Break backward compatibility unless necessary
-- Use PHP without strict typing
-- Commit sensitive information
-- Mix multiple concerns in a single PR
-
-## Reporting Issues
-
-When reporting issues, please include:
-
-- PHP version
-- Library version
-- Complete error messages
-- Minimal reproducible example
-- Expected vs actual behavior
-
-## Questions
-
-If you have questions about contributing, feel free to:
-
-- Open an issue with the "question" label
-- Start a discussion in the repository discussions
+- [Getting Started](docs/contributing/getting-started.md) - Set up your development environment
+- [Guidelines](docs/contributing/guidelines.md) - Best practices
+- [Adding Formatters](docs/contributing/adding-formatters.md) - How to create new formatters
+- [Development](docs/contributing/development.md) - Testing, linting, and static analysis
+- [Submitting Changes](docs/contributing/submitting-changes.md) - Pull request process
+- [Commit Guidelines](docs/contributing/commit-guidelines.md) - How to write good commit messages
 
 Thank you for contributing to StringFormatter! 🎉

composer.json

@@ -22,7 +22,8 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "Respect\\StringFormatter\\Test\\": "tests/"
+            "Respect\\StringFormatter\\": ["docs/contributing/templates/php/src"],
+            "Respect\\StringFormatter\\Test\\": ["tests/", "docs/contributing/templates/php/tests"]
         }
     },
     "authors": [

docs/contributing/adding-formatters.md

@@ -0,0 +1,19 @@
+# Adding New Formatters
+
+StringFormatter is designed to be extensible. All formatters must implement the `Respect\StringFormatter\Formatter` interface.
+
+**Steps to add a new formatter:**
+
+1. **Create the formatter class**
+
+Copy and rename the [TemplateFormatter.php](templates/php/src/TemplateFormatter.php) as a starting point.
+
+2. **Create tests**
+
+Copy and rename the [TemplateFormatterTest.php](templates/php/tests/TemplateFormatterTest.php) as a starting point.
+
+3. **Add documentation**
+   - Create `docs/YourFormatter.md` following the [formatter documentation template](templates/formatter-documentation-template.md)
+
+4. **Update README.md**
+   - Add your formatter to the "Formatters" table

docs/contributing/commit-guidelines.md

@@ -0,0 +1,53 @@
+# Commit Message Guidelines
+
+Follow these guidelines for writing clear, consistent commit messages.
+
+## Title
+
+- Contains 5-116 characters
+- Start with capital letter (A-Z)
+- Use imperative mood ("Add feature" not "Added feature")
+- No ticket numbers in title (use footer instead)
+- No trailing whitespace
+
+## Body
+
+- Explain WHY and maybe a bit of HOW
+- Empty line required between title and body
+- Max 116 characters per line (except URLs, code blocks, footer annotations)
+- 5 characters
+
+## Footer
+
+Use trailers to provide additional context when there's value to it:
+
+- `Reference: https://github.com/example/project/issues/123` - Only when linking to a specific, relevant issue or PR
+- `Assisted-by: Tool/Agent (<Model/Version>)` - When AI assistance was provided
+
+## Examples
+
+### Good commit message
+
+```
+Add uppercase formatter with UTF-8 support
+
+The new UpperCaseFormatter provides proper UTF-8 handling for
+international characters, converting strings to uppercase while
+maintaining accent marks and special characters.
+
+This addresses the need for proper internationalization support
+when manipulating text in various languages.
+
+Reference: https://github.com/example/project/issues/123
+```
+
+### Bad commit message
+
+```
+added upper case stuff
+
+fixes #123
+```
+
+The bad example uses lowercase, doesn't explain the reasoning, and
+includes the issue number in the title instead of the footer.

docs/contributing/development.md

@@ -0,0 +1,33 @@
+# Development Commands
+
+| Command            | Description                      |
+| ------------------ | -------------------------------- |
+| `composer install` | Install dependencies             |
+| `composer test`    | Run all tests                    |
+| `composer lint`    | Check PSR-12 compliance          |
+| `composer format`  | Fix coding style automatically   |
+| `composer analyze` | Run static analysis with PHPStan |
+
+## Testing
+
+- **Unit tests**: Located in `tests/Unit/`
+- **Run all tests**: `composer test`
+
+All contributions must include tests that pass.
+
+## Code Style
+
+This project follows the PSR-12 coding standard via the Respect Coding Standard. Run the following command before submitting:
+
+```bash
+composer lint  # Check coding style
+composer format # Fix coding style automatically
+```
+
+## Static Analysis
+
+This project uses PHPStan for static analysis. Run:
+
+```bash
+composer analyze  # Run static analysis
+```