From eb495e308f458e6ba21b0738f6f42ee9b84ded73 Mon Sep 17 00:00:00 2001
From: Thomas Bartlett <67928676+thomas-bartlett@users.noreply.github.com>
Date: Thu, 22 Jan 2026 09:59:03 -0500
Subject: [PATCH] Add custom rules documentation and template.

---
 README.md                                     |  1 +
 docs/custom-rules.md                          | 79 +++++++++++++++++++
 .../templates/custom-rule-template.md.example | 32 ++++++++
 3 files changed, 112 insertions(+)
 create mode 100644 docs/custom-rules.md
 create mode 100644 sources/templates/custom-rule-template.md.example

diff --git a/README.md b/README.md
index e30bc60..3ca52c0 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,7 @@ python src/convert_to_ide_formats.py  # Generate skills/ and dist/
 ```
 
 **More options**: `python src/convert_to_ide_formats.py --help`  
+**Custom rules**: Create your own rules — see [Custom Rules](https://project-codeguard.org/custom-rules/)  
 **Maintainers**: See [CONTRIBUTING.md](CONTRIBUTING.md) for release process.
 
 ## Community
diff --git a/docs/custom-rules.md b/docs/custom-rules.md
new file mode 100644
index 0000000..e480eac
--- /dev/null
+++ b/docs/custom-rules.md
@@ -0,0 +1,79 @@
+# Custom Rules
+
+Create custom rules to enforce your own policies, compliance requirements, or coding standards.
+
+## Quick Start
+
+1. **Create a source folder** under `sources/`:
+   ```
+   sources/
+   ├── core/           # Project CodeGuard rules
+   ├── owasp/          # OWASP supplementary rules
+   └── my-rules/       # Your custom rules
+   ```
+
+2. **Copy the template** from `sources/templates/custom-rule-template.md.example` and customize it
+
+3. **Build with your rules**:
+   ```bash
+   uv run python src/convert_to_ide_formats.py --source core my-rules
+   ```
+
+## Frontmatter Schema
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Yes | Brief description of the rule |
+| `languages` | If `alwaysApply` is false | List of languages this rule applies to |
+| `alwaysApply` | No | If `true`, rule applies to all files (omit `languages`) |
+| `tags` | No | Categories for filtering: `authentication`, `data-security`, `infrastructure`, `privacy`, `secrets`, `web` |
+
+## CLI Reference
+
+### convert_to_ide_formats.py
+
+Converts source rules to IDE-specific formats.
+
+| Option | Description |
+|--------|-------------|
+| `--source` | Source folders under `sources/` to include. Default: `core` |
+| `--output-dir`, `-o` | Output directory for generated bundles. Default: `dist` |
+| `--tag` | Filter rules by tags (comma-separated, case-insensitive, AND logic) |
+
+**Examples:**
+
+```bash
+# Default: convert core rules only
+uv run python src/convert_to_ide_formats.py
+
+# Include multiple sources
+uv run python src/convert_to_ide_formats.py --source core owasp my-rules
+
+# Custom output directory
+uv run python src/convert_to_ide_formats.py --source core my-rules -o build
+
+# Filter to only rules tagged with data-security
+uv run python src/convert_to_ide_formats.py --tag data-security
+
+# Multiple tags (AND logic - rules must have ALL tags)
+uv run python src/convert_to_ide_formats.py --tag data-security,authentication
+```
+
+### validate_unified_rules.py
+
+Validates rule files have correct frontmatter and structure before building.
+
+```bash
+# Validate all rules in a directory
+uv run python src/validate_unified_rules.py sources/my-rules/
+
+# Validate all sources
+uv run python src/validate_unified_rules.py sources/
+```
+
+## Notes
+
+- Filenames must be unique across all sources
+- Use `.md` extension for all rule files
+- Rules are converted to all supported IDE formats
+- To add new tags, update `KNOWN_TAGS` in `src/tag_mappings.py`
diff --git a/sources/templates/custom-rule-template.md.example b/sources/templates/custom-rule-template.md.example
new file mode 100644
index 0000000..864987c
--- /dev/null
+++ b/sources/templates/custom-rule-template.md.example
@@ -0,0 +1,32 @@
+---
+description: Brief description of the rule
+languages:
+- python
+- javascript
+tags:
+- data-security
+alwaysApply: false
+---
+
+<!-- The content below is flexible - structure it to fit your use case -->
+
+## Rule Title
+
+Brief overview of what this rule enforces and why it matters.
+
+### Section Name
+- Guidance point with specific recommendation
+- Another specific requirement or best practice
+
+### Another Section
+- Additional guidance organized by topic
+- Keep points concise and actionable
+
+### Implementation Checklist
+- Verify requirement one is met
+- Confirm requirement two is implemented
+- Check that patterns are followed
+
+### Test Plan
+- Describe how to verify the rule is followed
+- Include specific test scenarios