taste-lints

Exact captured content · path skills/taste-lints/SKILL.md · sha256 8e10e29792a764e0… · revision 2c9a48510df3425df469d35f87579ff1817dada6

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`