feat: initial open marketplace with llm-security, config-audit, ultraplan-local

plugins/config-audit/skills/config-hierarchy/references/rules-directory.md

@@ -0,0 +1,169 @@
+# .claude/rules/ Directory Reference
+
+## Purpose
+
+The `.claude/rules/` directory allows modular organization of instructions with optional path scoping.
+
+## Location
+
+```
+project/
+├── .claude/
+│   └── rules/
+│       ├── code-style.md
+│       ├── testing.md
+│       └── api.md
+└── CLAUDE.md
+```
+
+## File Format
+
+Each rule file is a markdown file with optional frontmatter:
+
+```markdown
+---
+paths: ["src/**/*.ts", "src/**/*.tsx"]
+description: TypeScript code style rules
+---
+
+# TypeScript Rules
+
+## Formatting
+- Use 2-space indentation
+- Prefer single quotes
+
+## Types
+- Always use explicit types for function parameters
+- Avoid `any` type
+```
+
+## Frontmatter Options
+
+### paths (Official) / globs (Legacy)
+
+Array of glob patterns that scope when this rule applies.
+
+**Official field name:** `paths:` (as per Claude Code documentation)
+**Legacy/alternative:** `globs:` (also supported for backwards compatibility)
+
+Both fields behave identically - use `paths:` for new rules:
+
+```yaml
+---
+paths: ["src/**/*.ts"]  # Official - Only for TypeScript in src/
+---
+```
+
+```yaml
+---
+globs: ["src/**/*.ts"]  # Legacy - Still works, but prefer paths:
+---
+```
+
+```yaml
+---
+paths: ["tests/**/*", "**/*.test.ts"]  # Test files anywhere
+---
+```
+
+If no paths/globs specified, rule applies everywhere.
+
+**Note:** Config-audit normalizes both to `patterns` internally and tracks which field was used via `pattern_source`.
+
+### description
+
+Brief description of what the rule covers:
+
+```yaml
+---
+description: Code formatting and style preferences
+---
+```
+
+### alwaysApply
+
+Force rule to always be included regardless of current file:
+
+```yaml
+---
+alwaysApply: true
+---
+```
+
+## Loading Behavior
+
+1. Rules are loaded when entering relevant directories
+2. Glob patterns are matched against current file/directory
+3. Matching rules are included in context
+4. Non-matching rules are not loaded
+
+## Example Rules
+
+### code-style.md
+
+```markdown
+---
+paths: ["src/**/*"]
+description: Source code style
+---
+
+# Code Style
+
+- TypeScript > JavaScript
+- Explicit types for public API
+- Document exported functions
+```
+
+### testing.md
+
+```markdown
+---
+paths: ["tests/**/*", "**/*.test.ts", "**/*.spec.ts"]
+description: Testing guidelines
+---
+
+# Testing
+
+- Use Jest for unit tests
+- Descriptive test names
+- Arrange-Act-Assert pattern
+```
+
+### api.md
+
+```markdown
+---
+paths: ["src/api/**/*", "src/routes/**/*"]
+description: API development rules
+---
+
+# API Guidelines
+
+- RESTful conventions
+- Validate all inputs
+- Consistent error responses
+```
+
+## Best Practices
+
+1. **Split by concern**: One rule file per topic
+2. **Use specific globs**: Avoid overly broad patterns
+3. **Keep rules focused**: 200-500 words per file
+4. **Document purpose**: Use description frontmatter
+5. **Review periodically**: Remove outdated rules
+
+## Migration from CLAUDE.md
+
+To convert from monolithic CLAUDE.md to rules:
+
+1. Identify distinct sections in CLAUDE.md
+2. Create rule file for each section
+3. Add appropriate globs
+4. Remove sections from CLAUDE.md
+5. Test that rules load correctly
+
+## Debugging
+
+To see which rules are loaded:
+- Check Claude Code logs
+- Rules appear in context when relevant files are active