Merge pull request #146 from philoserf/refactor/rules-token-efficiency

refactor: optimize rules files for token efficiency

Author: philoserf

rules/bash.md

@@ -4,25 +4,11 @@ paths:
   - "bin/**"
 ---
 
-# Bash Rules
-
-## Code Quality Standards
-
-- All bash scripts must pass `shellcheck` without warnings or errors
-- All bash scripts must be formatted with `shfmt`
-- Run `shfmt --write <file>` to auto-format
-- Run `shellcheck <file>` to validate; fix all reported issues
-
-## Script Structure
-
-- Include shebang line (`#!/usr/bin/env bash` or `#!/bin/bash` for portable scripts)
-- Use bash idioms and conventions
+- Must pass `shellcheck` and `shfmt`
+- Run `shfmt --write <file>` to format; `shellcheck <file>` to validate
+- Include shebang line (`#!/usr/bin/env bash` or `#!/bin/bash`)
 - Quote variables to prevent word splitting: `"$var"` not `$var`
 - Check exit codes and handle errors explicitly
 - Use meaningful names for functions and variables
-
-## Defensive Programming
-
-- Set error handling flags where appropriate: `set -euo pipefail`
+- Set error handling flags: `set -euo pipefail`
 - Avoid bare `grep` or `sed` without explicit error handling
-- Don't ignore command failures silently

rules/git.md

@@ -3,41 +3,15 @@ paths:
   - "**"
 ---
 
-# Git & GitHub Rules
-
-## Branch Strategy
-
 - Always work on feature branches, never directly on `main`
-- Create descriptive feature branch names (e.g., `feature/add-auth`, `fix/login-bug`, `docs/update-readme`)
-- Branch from `main` unless otherwise specified
-
-## Commits
-
+- Create descriptive branch names (e.g., `feature/add-auth`, `fix/login-bug`, `docs/update-readme`)
 - Write atomic commits with clear, descriptive messages
 - Use conventional commit format when applicable (e.g., `feat:`, `fix:`, `docs:`, `refactor:`)
 - Keep commits focused on a single logical change
 - Do not commit secrets, credentials, or environment files
-
-## Push
-
-- **Ask before pushing**: Always confirm with the user before running `git push`
-- Verify the branch name and changes are correct before pushing
-- Push to the feature branch, not to `main`
-
-## Pull Requests
-
-- **Ask before creating a PR**: Always confirm with the user before running `gh pr create`
-- Provide a summary of what the PR does
-- Reference relevant issues if applicable
-- Ensure all commits are pushed to the feature branch before creating a PR
-- Use descriptive PR titles (consistent with branch naming and commit messages)
+- **Always confirm with user before running `git push` or `gh pr create`**
+- Use `git status` and `git diff` to review changes before committing
+- Use `gh` CLI for GitHub operations (PRs, issues, workflows)
 - Verify branch is up-to-date with `main` before creating a PR
-
-## General Workflow
-
-- Use `git status` to review changes before committing
-- Use `git diff` to inspect changes in detail
-- Use `gh` CLI for GitHub-specific operations (PRs, issues, workflows)
-- Use `gh api` for GitHub API interactions when needed
-- Commit frequently with clear messages
-- Keep branch history clean; avoid unnecessary merge commits when possible
+- Use descriptive PR titles; reference relevant issues
+- Keep branch history clean; avoid unnecessary merge commits

rules/images.md

@@ -0,0 +1,10 @@
+---
+paths:
+  - "**/*.{jpg,jpeg,png,gif,webp,bmp,tiff,heic}"
+---
+
+- **Max 20 images per batch** — stop and confirm before continuing
+- **Max 50 images per session** — start new conversation before limit
+- Use metadata tools (exiftool) over Read when possible
+- Use OCR tools for text extraction
+- Report progress after each batch: processed, remaining, "Continue?"

rules/markdown.md

@@ -3,23 +3,9 @@ paths:
   - "**/*.md"
 ---
 
-# Markdown Rules
-
-## Formatting & Linting
-
-- All markdown must pass `prettier` formatting
-- All markdown must pass `markdownlint` validation
+- Must pass `prettier` and `markdownlint`
 - Run `bunx prettier --write <file>` to format
 - Run `bunx markdownlint-cli2 <file>` to validate
-
-## Markdownlint Rules
-
-- **MD041 (required)**: Every code block must have a language specified (e.g., ` ```bash `, ` ```ts `, ` ```json `)
-  - Use `text` when no other language applies
-- **MD013 (exempted)**: Line length is not enforced; do not break lines artificially to satisfy line limits
-
-## Code Blocks
-
-- Always specify a language tag for code blocks
-- Use language-appropriate tags: `bash`, `sh`, `ts`, `tsx`, `js`, `json`, `yaml`, `python`, `sql`, `html`, `css`, etc.
-- Use `text` for generic or plain text blocks
+- **MD041**: Every code block must have a language tag (e.g., ` ```bash `, ` ```ts `, ` ```json `); use `text` when no other applies
+- **MD013**: Line length is not enforced
+- Always specify language tags: `bash`, `sh`, `ts`, `tsx`, `js`, `json`, `yaml`, `python`, `sql`, `html`, `css`, etc.

rules/pdf.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "**/*.pdf"
+---
+
+- **Max 10 PDFs per batch** — stop and confirm before continuing
+- **Max 30 PDFs per session** — start new conversation before limit
+- Use text extraction tools (pdftotext, pymupdf) over Read
+- Use pdf-renamer skill tools for simple renaming tasks
+- Use pdf skill for more involved tasks
+- Report progress after each batch: processed, remaining, "Continue?"

rules/python.md

@@ -3,39 +3,20 @@ paths:
   - "**/*.py"
 ---
 
-# Python Rules
-
-## Package Management & Execution
-
-- Use `uv` for all dependency and environment management
-- Use `uvx` to run Python tools and scripts from PyPI
-- For self-contained scripts, use PEP 723 inline dependencies in script headers
-- Never use `pip`, `pip3`, `poetry`, or `pipenv`
-
-## Inline Dependencies (PEP 723)
-
-Self-contained scripts must declare dependencies as PEP 723 script metadata. Example:
-
+- Use `uv` exclusively (never pip/poetry/pipenv); use `uvx` for PyPI tools
+- Self-contained scripts must use PEP 723 inline dependencies:
 ```python
 #!/usr/bin/env python3
 # /// script
 # requires-python = ">=3.8"
-# dependencies = [
-#     "requests>=2.28",
-#     "click>=8.0",
-# ]
+# dependencies = ["requests>=2.28", "click>=8.0"]
 # ///
 
 import requests
 import click
 ```
-
-Run with: `uvx --script <file.py>`
-
-## Code Style
-
-- Use Black for code formatting
-- Use Ruff for linting
+- Run with: `uvx --script <file.py>`
+- Use Black for formatting and Ruff for linting
 - Use type hints for function signatures
 - Prefer f-strings for string formatting
 - Use pathlib for filesystem operations

rules/typescript.md

@@ -8,34 +8,13 @@ paths:
   - "tsconfig.json"
 ---
 
-# TypeScript Rules
-
-## Tooling
-
-- Use `bunx` to run external tools and CLI utilities (e.g., `bunx tsx`, `bunx biome check`, `bunx esbuild`)
-- Use `bun run <script>` for package.json scripts defined in `scripts` section
-- Never use `npm` or `yarn`—use `bun install` for dependencies
-
-## Runtime & Execution
-
-- Target Bun as the runtime. Use Bun's native APIs where applicable (file I/O, testing, bundling)
-- Use `bun run` to execute scripts defined in package.json
-- Use Bun's native test runner with `bun test` for all test files (_.test.ts,_.spec.ts)
-
-## Code Style & Linting
-
+- Use `bunx` for external tools, `bun run` for scripts, `bun install` for dependencies—never npm/yarn
+- Target Bun as the runtime; use Bun's native APIs where applicable (file I/O, testing, bundling)
+- Use Bun's native test runner with `bun test` for all test files (_.test.ts, _.spec.ts)
 - Biome is the single source of truth for formatting and linting
 - Follow biome.json configuration exactly; do not suggest overrides without explicit request
-- Run `biome check --fix` or `biome format --write` via `bun run` script when changes are needed
+- Run `biome check --fix` or `biome format --write` via `bun run` when changes are needed
 - TypeScript strict mode is enabled; submit to its defaults unless there's a strong reason to deviate
-
-## Packaging & Building
-
 - Use Bun's bundler (`bun build`) for creating bundles
-- Use Bun's package exports feature in package.json for multi-entry publishing
 - Ensure all TypeScript compiles cleanly with `tsc --noEmit` if a build step exists
-
-## Project Structure
-
-- Respect existing directory structure (e.g., bin/, src/, tests/)
-- Follow the conventions established in existing files within each directory
+- Respect existing directory structure (e.g., bin/, src/, tests/) and conventions