chore: Improve repository structure with templates and documentation

.github/CODEOWNERS

@@ -0,0 +1,22 @@
+# Code owners for msgtrace-sdk
+#
+# These owners will be automatically requested for review
+# when someone opens a pull request.
+
+# Default owner for everything
+* @vilsonrodrigues
+
+# Documentation
+/docs/ @vilsonrodrigues
+*.md @vilsonrodrigues
+
+# CI/CD and automation
+/.github/ @vilsonrodrigues
+/scripts/ @vilsonrodrigues
+
+# Core SDK
+/src/msgtrace/sdk/ @vilsonrodrigues
+/src/msgtrace/core/ @vilsonrodrigues
+
+# Tests
+/tests/ @vilsonrodrigues

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,91 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the information below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of what the bug is.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior
+      placeholder: |
+        1. Install msgtrace-sdk
+        2. Run code with '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+      placeholder: What actually happened instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: code
+    attributes:
+      label: Code Example
+      description: Minimal code to reproduce the issue
+      render: python
+      placeholder: |
+        from msgtrace.sdk import Spans, MsgTraceAttributes
+
+        # Your code here
+
+  - type: input
+    id: version
+    attributes:
+      label: msgtrace-sdk Version
+      description: What version are you using?
+      placeholder: "1.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: What Python version are you using?
+      placeholder: "3.11"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: What OS are you running?
+      placeholder: "Ubuntu 22.04 / macOS 14 / Windows 11"
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other information that might be helpful (logs, screenshots, etc.)
+      placeholder: Add any other context about the problem here

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,61 @@
+name: Feature Request
+description: Suggest an idea or enhancement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature! Please describe your idea below.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: Is your feature request related to a problem? Please describe.
+      placeholder: I'm frustrated when...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like
+      placeholder: I would like to be able to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Have you considered any alternative solutions or workarounds?
+      placeholder: I've tried...
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Describe your use case and how this feature would help
+      placeholder: This would help me...
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Code Example (Optional)
+      description: If applicable, show how you'd like to use this feature
+      render: python
+      placeholder: |
+        from msgtrace.sdk import Spans
+
+        # Your desired API usage
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other information that might be helpful
+      placeholder: Add any other context or screenshots about the feature request here

.github/pull_request_template.md

@@ -0,0 +1,54 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Changes
+
+<!-- List the main changes in this PR -->
+-
+-
+-
+
+## Type of Change
+
+<!-- Mark the relevant option with an "x" -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code refactoring
+- [ ] Performance improvement
+- [ ] Test improvement
+- [ ] CI/CD improvement
+- [ ] Chore/maintenance
+
+## Testing
+
+<!-- Describe how you tested these changes -->
+- [ ] Tests pass locally (`uv run pytest -v`)
+- [ ] Added new tests for this change
+- [ ] Updated existing tests
+
+## Documentation
+
+<!-- Check if documentation needs updating -->
+- [ ] Updated README.md (if API changed)
+- [ ] Updated CHANGELOG.md (if notable change)
+- [ ] Added/updated code comments
+- [ ] Added/updated docstrings
+
+## Checklist
+
+<!-- Mark completed items with an "x" -->
+- [ ] Code formatted (`uv run ruff format`)
+- [ ] Lint checks pass (`uv run ruff check`)
+- [ ] Tests pass (`uv run pytest -v`)
+- [ ] **Version NOT changed** (maintainers bump version after merge)
+- [ ] Commit messages follow [conventional commits](https://www.conventionalcommits.org/)
+- [ ] No breaking changes (or documented above)
+- [ ] Added tests for new features
+- [ ] Documentation is up to date
+
+## Additional Notes
+
+<!-- Any additional information reviewers should know -->

.github/release-drafter.yml

@@ -2,36 +2,49 @@ name-template: 'v$RESOLVED_VERSION'
 tag-template: 'v$RESOLVED_VERSION'
 
 categories:
+  - title: '🚨 Breaking Changes'
+    labels:
+      - 'breaking-change'
+      - 'breaking'
   - title: '🚀 Features'
     labels:
       - 'enhancement'
       - 'feat'
+      - 'feature'
   - title: '🐛 Bug Fixes'
     labels:
       - 'bug'
       - 'fix'
+  - title: '⚡ Performance'
+    labels:
+      - 'performance'
+      - 'perf'
+  - title: '🔐 Security'
+    labels:
+      - 'security'
   - title: '📚 Documentation'
     labels:
       - 'documentation'
       - 'docs'
+  - title: '🔄 Refactoring'
+    labels:
+      - 'refactor'
+      - 'refactoring'
   - title: '🧪 Tests'
     labels:
       - 'tests'
       - 'test'
-  - title: '⚡ Performance'
+  - title: '🤖 CI/CD'
     labels:
-      - 'performance'
-      - 'perf'
+      - 'ci'
+      - 'ci-cd'
+  - title: '📦 Dependencies'
+    labels:
+      - 'dependencies'
   - title: '🔧 Maintenance'
     labels:
       - 'maintenance'
       - 'chore'
-  - title: '🔐 Security'
-    labels:
-      - 'security'
-  - title: '📦 Dependencies'
-    labels:
-      - 'dependencies'
 
 change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
 change-title-escapes: '\<*_&'

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  # Security: Detect secrets and credentials
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.23.1
+    hooks:
+      - id: gitleaks
+
+  # UV: Keep uv.lock in sync
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.8.3
+    hooks:
+      - id: uv-lock
+
+  # Ruff: Linting and formatting
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

CONTRIBUTING.md

@@ -491,6 +491,67 @@ https://github.com/msgflux/msgtrace-sdk/settings/secrets/actions
 - `PYPI_API_TOKEN` - From https://pypi.org/manage/account/token/
 - `TEST_PYPI_API_TOKEN` - From https://test.pypi.org/manage/account/token/
 
+## 📦 Development Setup
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/msgflux/msgtrace-sdk.git
+cd msgtrace-sdk
+
+# Install dependencies
+uv sync
+
+# Install with dev dependencies
+uv sync --group dev
+```
+
+### Testing
+
+```bash
+# Run tests
+uv run pytest -v
+
+# With coverage
+uv run pytest -v --cov=src/msgtrace --cov-report=html
+
+# Run specific test
+uv run pytest tests/test_attributes.py -v
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run ruff format
+
+# Lint
+uv run ruff check
+
+# Auto-fix
+uv run ruff check --fix
+```
+
+### CI/CD
+
+The project uses GitHub Actions for CI/CD:
+
+- **CI** (`ci.yml`) - Lint, format, test on Python 3.10-3.13
+- **Validate Release** (`validate-release.yml`) - Security validation for releases
+- **Publish** (`publish.yml`) - Publishes to PyPI after validation
+- **Merge Bot** (`merge-bot.yml`) - Command-based PR merging with `/merge` and `/update`
+- **Stale Bot** (`stale.yml`) - Closes stale issues/PRs
+- **Release Drafter** (`release-drafter.yml`) - Auto-generates release notes
+- **CodeQL** (`codeql.yml`) - Security scanning
+- **Dependabot** - Automated dependency updates
+
+See [AUTOMATION.md](docs/AUTOMATION.md) for detailed automation documentation.
+
+### Release Process
+
+To release a new version, use the automated release script. See the "For Maintainers: Creating Releases" section above for detailed instructions.
+
 ## 📚 Resources
 
 - [Conventional Commits](https://www.conventionalcommits.org/)
@@ -499,3 +560,5 @@ https://github.com/msgflux/msgtrace-sdk/settings/secrets/actions
 - [Ruff Documentation](https://docs.astral.sh/ruff/)
 - [pytest Documentation](https://docs.pytest.org/)
 - [GitHub Actions](https://docs.github.com/en/actions)
+- [Automation Guide](docs/AUTOMATION.md)
+- [Roadmap](docs/ROADMAP.md)