--- name: taste-lints version: 1.0.0 description: Use when you say `run taste lints`, `check file size`, or `lint taste invariants`. Custom lints with agent-readable remediation instructions for file size, naming conventions, structured logging, and complexity. license: MIT metadata: routing: role: lifecycle invoker: review trigger: review invokes taste-lints as one of its four local quality axes user-facing: false --- # Taste Lints Custom lints where error messages become agent-readable remediation instructions. Inspired by [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/): > "We statically enforce structured logging, naming conventions for schemas and types, > file size limits, and platform-specific reliability requirements with custom lints. > Because the lints are custom, we write the error messages to inject remediation > instructions into agent context." ## Triggers | Trigger Phrase | Operation | |----------------|-----------| | `run taste lints` | taste_lints.py on staged or specified files | | `check file size` | taste_lints.py with file-size rule only | | `check naming conventions` | taste_lints.py with naming rule only | | `lint taste invariants` | taste_lints.py full scan | | `taste lint report` | taste_lints.py with JSON output | ## When to Use Use this skill when: - Writing or editing source files (catch taste violations early) - Preparing code for PR submission - Reviewing code for style and convention compliance - Adding new files to the project ## Taste Invariants ### 1. File Size Limits Files exceeding line thresholds indicate poor cohesion. | Threshold | Lines | Severity | |-----------|-------|----------| | Warning | 301-500 | warning | | Error | 501+ | error | ### 2. Naming Conventions | Pattern | Rule | Applies To | |---------|------|------------| | `snake_case` | Python files, functions, variables | `*.py` | | `kebab-case` | Skill directories, YAML files | `.claude/skills/`, `*.yml` | | `PascalCase` | PowerShell functions, classes | `*.ps1`, `*.psm1` | | `UPPER_CASE` | Constants, environment variables | All languages | | `invoke_` prefix | Hook scripts | `.claude/hooks/` | A YAML stem may hold dot-separated kebab-case segments, such as `ci.pr.yml`. A leading dot is also valid, because tools require names like `.coderabbit.yaml`. `__init__.py` and `__main__.py` are exempt from `snake_case`, because Python requires those names. Every name a naming remediation suggests passes the rule that reported it. A name that cannot start with a letter gets an `item` prefix, so `1config.yml` becomes `item-1config.yml`. ### 3. Function Complexity Functions exceeding cyclomatic complexity 10 need decomposition. ### 4. Skill Prompt Size Skills exceeding 500 lines need progressive disclosure refactoring. ## Process 1. Run `taste_lints.py` with the target files, using a locator from the Scripts section. Put the files inside its argument list. 2. Review AGENT_REMEDIATION blocks in output 3. Apply suggested fixes 4. Re-run to confirm compliance ## Scripts | Script | Platform | Usage | |--------|----------|-------| | `scripts/taste_lints.py` | Python 3.11+ | Scan staged files, diff scopes, directories, or explicit files for taste invariant violations | ```bash # Scan staged files ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/taste-lints/scripts/taste_lints.py --git-staged; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) # Scope to a pull request diff (only files changed vs the base branch) ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/taste-lints/scripts/taste_lints.py --diff-scope "origin/$BASE_BRANCH"; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) # Scan specific files ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/taste-lints/scripts/taste_lints.py path/to/file.py; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) # Scan a directory ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/taste-lints/scripts/taste_lints.py --directory src/; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) # Text output lists at most 100 violations (errors first when cut); --max-violations 0 in the locator lists all # JSON output (never cut) ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/taste-lints/scripts/taste_lints.py --format json --git-staged; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) # Run specific rules only ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/taste-lints/scripts/taste_lints.py --rules file-size,naming; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 ) ``` ## Exit Codes | Code | Meaning | |------|---------| | 0 | No violations found | | 1 | Script error (bad arguments, file not found) | | 10 | Violations detected | ## Verification After execution: - [ ] Script exits with code 0 for clean input or 10 when violations are expected - [ ] Output lists every scanned file count and violation count - [ ] AGENT_REMEDIATION blocks include actionable fixes for each violation - [ ] JSON output parses when `--format json` is used ## Suppression Add a comment to suppress a specific rule on a file: ```python # taste-lint: ignore file-size ``` Valid rules: `file-size`, `naming`, `complexity`, `skill-size`