ai-toolkit-rules

name	ai-toolkit-rules
description	Mandatory engineering, security, testing, git, performance, quality, and response rules. Claude MUST load this skill for every technical, coding, debugging, review, architecture, DevOps, data, or file-editing task in Chat or Cowork.
user-invocable	true

AI Toolkit Rules

Apply every relevant rule below before acting. Treat MUST/NEVER language as mandatory.

Source: app/rules/claude-toolkit-rules.md

Claude Toolkit

Shared AI development toolkit — lifecycle hooks, safety constitution, multi-platform support.

Skill Tiers

• Tier 1 — single-agent: /debug, /review, /refactor, /analyze, /docs, /plan, /explain, /tdd, /triage-issue
• Tier 1.5 — planning: /write-a-prd → /prd-to-plan → /prd-to-issues; design: /design-an-interface, /architecture-audit, /refactor-plan
• Tier 2 — multi-agent: /workflow <type> (feature-development, backend-feature, frontend-feature, api-design, database-evolution, test-coverage, security-audit, debugging, incident-response, spike, codebase-onboarding, performance-optimization, infrastructure-change, application-deploy, proactive-troubleshooting)
• Tier 3 — custom: /orchestrate <desc> (3–6 agents) | /swarm <mode> <desc> (map-reduce | consensus | relay)

Path Safety

• NEVER guess or hallucinate user home directory paths
• Use ~ or $HOME instead of hardcoded /Users/<username>/ or /home/<username>/
• When an absolute path is needed, run echo $HOME first to get the correct value

User Preferences

• Style: Direct & efficient. No pleasantries. Measurable results.
• Methodology: Provide >=3 alternatives. Use Socratic questioning.
• Review: Apply "Devil's Advocate" critique to decisions.

Source: app/rules/git-conventions.md

Git Conventions

• Do NOT add Co-Authored-By: Claude or any AI co-authorship to commits
• Do NOT add Claude signatures or attribution to commit messages
• Conventional commits format: feat:, fix:, docs:, refactor:, test:, chore:

Source: app/rules/output-mode.md

Output Mode

output-mode: concise

Default response mode for this project is concise. The brand-voice skill (when present in ai-toolkit) auto-loads its concise rules; assistants without that skill should still apply the directives below.

Concise Mode Directives

• No preamble. Skip "I'll now...", "Sure, let me...", "Great question!" and similar warm-ups. Start with the answer.
• Lead with the result. Conclusion or output first; explanation only if asked or non-obvious.
• Max 3 sentences per closed question. Yes/no, single-fact, or "where is X" answers stay under three sentences.
• Tables and lists over prose when comparing options, listing steps, or showing values.
• No trailing summaries. If the diff or output already shows what changed, do not restate it.
• Drop filler adjectives. No "nice", "great", "powerful", "robust" unless the user asked for evaluation.
• Cite file paths as path:line instead of paragraphs describing where things live.
• Reserve longer prose for: architecture proposals, trade-off analyses, plans with risks. Everything else: terse.

When to escalate to verbose

• User explicitly asks: "explain in detail", "walk me through", "give me the full picture".
• Reporting a non-obvious failure mode where missing context would mislead.
• Architecture / RFC / ADR / trade-off documents — those have their own structure.

How to override

• Per-session: /brand-voice default (or /brand-voice strict for even tighter)
• Per-project: change this rule's output-mode: value in the project's CLAUDE.md
• Permanent removal: re-run ai-toolkit install --skip rules or strip the <!-- TOOLKIT:output-mode --> block manually

Source: app/rules/quality-gates.md

Quality Gates & Mandatory Practices

MANDATORY PRACTICES

1. Plan First: Tasks >1h require Plan, Success Criteria, and Pre-Mortem.
2. Quality Gates:
   • ruff check . (0 errors)
   • mypy --strict src/ (0 errors)
   • pytest --cov=src (>70% coverage)
   • Type Safety: 100% public APIs, >60% internal.
3. Security: No secrets in code, sanitization, auth z/n.

Source: app/rules/common/coding-style.md

Universal Coding Style

Principles

• KISS: simplest solution that works. Clever code is a liability. If 200 lines could be 50, rewrite.
• DRY: extract when you repeat 3+ times, not before.
• YAGNI: do not build features "just in case." No abstractions for single-use code.
• Prefer immutability: use const, final, val, let by default.
• Fail fast: validate inputs at boundaries, return early on errors.
• State assumptions before coding. If uncertain or multiple interpretations exist, ask — don't pick silently.

Naming

• Use descriptive names that reveal intent (remainingRetries, not r).
• Boolean variables/functions: prefix with is, has, can, should.
• Functions: verb + noun (fetchUser, calculateTotal, validateInput).
• Avoid abbreviations unless universally understood (id, url, http).
• Collections use plural nouns (users, orderItems).

Functions

• Max 20-30 lines per function. If longer, extract.
• Max 3 parameters. Beyond that, use an options/config object.
• Single responsibility: one function does one thing.
• Pure functions preferred: same input, same output, no side effects.
• Avoid boolean parameters: use separate functions or enums.

File Organization

• One primary concept per file (class, module, component).
• Group imports: stdlib, external, internal, relative.
• Constants at top, public API before private helpers.
• Keep files under 300 lines. Split when they grow.

Comments

• Code should be self-documenting. Comment why, not what.
• Delete commented-out code. That is what version control is for.
• Use TODO/FIXME with ticket references: // TODO(PROJ-123): migrate to v2.
• Document public APIs with doc comments (JSDoc, docstrings, etc.).

Formatting

• Use project formatter (Prettier, Black, gofmt, rustfmt). No manual formatting debates.
• Consistent indentation: follow project convention (spaces vs tabs, width).
• Max line length: 80-120 characters depending on language convention.
• Trailing commas in multi-line structures (where language supports).

Surgical Changes

• Touch only what the task requires. Every changed line should trace to the request.
• Match existing style, even if you would do it differently.
• Do not "improve" adjacent code, comments, or formatting unprompted.
• Orphan cleanup: remove imports/variables/functions that YOUR changes made unused.

No Dead Code (Constitution Art. VI.1)

• When a refactor leaves a file, class, function, import, l10n key, or variable unused, DELETE it in the same change. Verify via grep that zero references remain in the repo.
• This applies to pre-existing code too, if your work makes its unusedness verifiable. "Legacy", "separate refactor", "out of scope", or "świadome pominięcie" are NOT valid excuses.
• Before claiming the task done: grep for every symbol you removed or renamed; fix orphaned references.

Fix Every Found Bug (Constitution Art. VI.2)

• A bug, missing test for changed behavior, or stale doc discovered while working on a task MUST be fixed in the same change — not deferred to "second step", "separate PR", or "świadome pominięcie".
• When behavior changes, update integration AND unit tests AND the affected docs alongside. A unit test on a new helper is not sufficient when the behavior is exposed over an API — add the integration test too.
• Legitimate deferral exists ONLY when: (a) the fix requires a user decision — in that case, surface it explicitly and ask, don't bury in a summary; or (b) the issue is genuinely unrelated to the current change surface.
• Before marking done: re-read the diff and confirm no orphaned references, no missing test coverage for changed paths, no stale docs. If any are present, keep working.

Goal-Driven Execution

• Transform vague tasks into verifiable goals before starting.
• For multi-step work, state a brief plan with verification per step: 1. [Step] → verify: [check]
• Strong success criteria enable independent looping. Weak criteria ("make it work") require clarification — ask first.

JSON Wire Format Conventions

• Field names (keys): camelCase. Aligns with JSON:API spec, Google JSON Style Guide, and framework defaults (Symfony Serializer, Spring Jackson, json_serializable for Dart). No public major API uses snake_case keys in modern designs except ecosystem-bound cases (Rails/Django APIs defaulting to ecosystem convention).
• Enum / status / permission / domain values: UPPER_SNAKE_CASE. Community consensus: Protocol Buffers style guide (mandatory), Google AIP-126 / api-linter (enforced), Zalando Rule #240, Java/Kotlin/C++/Python enum convention. lowercase snake_case (Stripe-style) is a legitimate outlier but not consensus.
• Avoid camelCase for enum values — no major public API uses it, loses visual distinction between keys and values.
• Pick one convention per project and enforce it with a CI grep gate. Mixing conventions inside a single API surface is the worst outcome.
• External contracts (Stripe, GitHub, webhooks you receive) follow their own convention — map to your project convention at the adapter boundary, do not leak their keys past it.

Anti-Patterns to Avoid

• God classes/modules with 500+ lines and multiple responsibilities.
• Deep nesting (>3 levels): use early returns and extract functions.
• Magic numbers/strings: use named constants.
• Mutable global state: use dependency injection instead.

Source: app/rules/common/git-workflow.md

Git Workflow Rules

Commit Messages

• Use conventional commits: feat:, fix:, docs:, refactor:, test:, chore:.
• First line: imperative mood, max 72 chars (feat: add user registration endpoint).
• Body (optional): explain why, not what. The diff shows what.
• Reference tickets: fix: prevent duplicate orders (PROJ-456).

Commit Practices

• Commit small, atomic changes. One commit = one logical change.
• Never commit: secrets, .env files, build artifacts, large binaries.
• Never commit broken code to main. Use feature branches.
• Squash fixup commits before merging to keep history clean.

Branching

• main is always deployable. Protect it with required reviews and CI.
• Feature branches: feat/user-registration, fix/order-total-calc.
• Delete branches after merge. Stale branches are clutter.
• Rebase feature branches on main before PR to keep linear history.

Pull Requests

• Keep PRs small: <400 lines changed. Split large features into stacked PRs.
• PR title follows conventional commit format.
• Include: summary, test plan, and screenshots/recordings for UI changes.
• Require at least one approval before merge.

Code Review

• Review for: correctness, security, performance, readability.
• Approve with comments if nits only. Block for: bugs, security, missing tests.
• Respond to reviews within 24 hours. Do not let PRs rot.

Tags and Releases

• Use semantic versioning: MAJOR.MINOR.PATCH.
• Tag releases: git tag v1.2.3. Automate changelog from commits.

Recovery

• Use git stash for WIP, not unfinished commits.
• Prefer git revert over git reset --hard on shared branches.
• Never force-push to main or shared branches.

Source: app/rules/common/performance.md

Universal Performance Rules

Mindset

• Profile before optimizing. Measure, do not guess.
• Premature optimization is the root of all evil. Ship correct first, fast second.
• Set performance budgets and test against them in CI.

Database

• Fix N+1 queries: use JOINs, eager loading, or batch fetching.
• Add indexes for columns used in WHERE, ORDER BY, and JOIN clauses.
• Use EXPLAIN/ANALYZE to verify query plans. Avoid full table scans.
• Paginate all list endpoints. Never return unbounded result sets.
• Use connection pooling. Never open a new connection per request.

Caching

• Cache at the right layer: CDN > reverse proxy > application > database.
• Set explicit TTLs. Stale cache is worse than no cache.
• Cache immutable or slowly-changing data. Avoid caching user-specific mutable data.
• Use cache-aside pattern: check cache, fetch on miss, populate cache.
• Include cache invalidation strategy before adding any cache.

I/O and Network

• Async/non-blocking for I/O-bound work. Thread pools for CPU-bound work.
• Batch operations where possible: bulk inserts, batch API calls.
• Set timeouts on all external calls: HTTP, database, message queues.
• Use streaming for large payloads instead of loading everything into memory.

Memory

• Preallocate collections when size is known.
• Use streaming/iterators for large datasets instead of loading all into memory.
• Watch for memory leaks: unclosed connections, growing caches, event listener accumulation.
• Avoid unnecessary copies/clones of large data structures.

API Performance

• Compress responses (gzip/brotli). Return only requested fields.
• Use HTTP/2 or HTTP/3 where supported.
• Implement request deduplication for identical concurrent requests.
• Return 202 Accepted for long-running operations, process async.

Monitoring

• Track p50, p95, p99 latencies, not just averages.
• Alert on latency regressions, not just errors.
• Log slow queries (>100ms) and slow endpoints (>500ms).

Source: app/rules/common/security.md

Universal Security Rules

Input Validation

• Validate ALL input at API boundaries. Trust nothing from clients.
• Use allowlists over denylists: define what IS valid, reject everything else.
• Validate type, length, format, and range for every input field.
• Sanitize output for the target context (HTML, SQL, shell, URL).

Authentication

• Hash passwords with bcrypt, scrypt, or argon2. Never MD5/SHA for passwords.
• Use constant-time comparison for tokens and secrets.
• Implement rate limiting on auth endpoints (login, register, password reset).
• Enforce MFA for admin and sensitive operations.

Authorization

• Check permissions on every request, not just at the UI level.
• Use principle of least privilege: default deny, explicitly grant.
• Validate resource ownership: user can only access their own data.
• Never rely on client-side authorization checks.

Secrets Management

• Never hardcode secrets in source code. Use environment variables or vaults.
• Rotate secrets regularly. Automate rotation where possible.
• Use different secrets per environment (dev/staging/prod).
• Add .env to .gitignore. Use .env.example as a template.

SQL Injection Prevention

• Always use parameterized queries or ORM query builders.
• Never concatenate user input into SQL strings.
• Validate and cast types before using in queries.

XSS Prevention

• Escape all dynamic content rendered in HTML.
• Use Content Security Policy (CSP) headers.
• Set HttpOnly and Secure flags on authentication cookies.
• Avoid innerHTML, eval(), and dangerouslySetInnerHTML.

API Security

• Use HTTPS everywhere. No exceptions.
• Implement rate limiting and request throttling.
• Set CORS headers explicitly. Never use * in production.
• Return generic error messages to clients. Log details server-side.
• Use security headers: HSTS, X-Content-Type-Options, X-Frame-Options.

Dependencies

• Audit dependencies regularly (npm audit, pip-audit, cargo audit).
• Pin dependency versions. Use lockfiles.
• Remove unused dependencies. Each dependency is an attack surface.

Logging

• Never log passwords, tokens, credit cards, or PII.
• Log security events: failed logins, permission denials, input validation failures.
• Use structured logging with correlation IDs for traceability.

Source: app/rules/common/testing.md

Universal Testing Rules

Test Structure

• Use Arrange-Act-Assert (AAA) pattern in every test.
• One logical assertion per test. Multiple assert calls are fine if testing one behavior.
• Test names describe behavior: test_returns_404_when_user_not_found.
• Keep tests independent: no shared mutable state between tests.

Test Organization

• Mirror source structure: src/auth/login.ts -> tests/auth/login.test.ts.
• Separate unit, integration, and e2e tests into distinct directories or markers.
• Shared fixtures go in conftest.py, test-utils.ts, or equivalent.

What to Test

• Test behavior, not implementation. Tests should survive refactors.
• Cover: happy path, error cases, edge cases, boundary values.
• New code: 100% coverage. Overall project: >70%.
• Critical paths (auth, payments, data mutations): always tested.

What NOT to Test

• Framework internals (ORM save, HTTP library send).
• Trivial getters/setters with no logic.
• Third-party library correctness.
• Private methods directly: test through public API.

Mocking

• Mock at boundaries: HTTP clients, databases, file systems, clocks.
• Prefer fakes over mocks when logic is complex.
• Never mock the thing you are testing.
• Reset mocks between tests to prevent leakage.

Test Quality

• Tests must be deterministic: no flaky tests allowed.
• Tests must be fast: unit tests <100ms each, test suite <60s.
• Avoid sleep in tests: use polling, events, or test clocks.
• Do not test implementation details (private methods, internal state).

Coverage

• Measure coverage but do not chase 100%: focus on critical paths.
• Coverage gaps in error handling and edge cases are worse than gaps in happy paths.
• New PRs must not decrease overall coverage.

Test Data

• Use factories/builders to create test data, not raw constructors.
• Keep test data minimal: only set fields relevant to the test.
• Do not share mutable test data across tests.
• Use realistic but not real data (no production data in tests).