Download the exact captured file
---
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`