# AI Toolkit Rules

> 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.

- Skill: `softspark/ai-toolkit-rules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add softspark/ai-toolkit-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/softspark/ai-toolkit-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: softspark (https://skillmd.com/u/softspark)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/softspark/ai-toolkit-rules

---


# 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 a hardcoded `/Users` or `/home` prefix followed
  by a user name. The literal prefix is deliberately not written out here: the
  plugin export scans shipped files for exactly that pattern, so an example of
  the mistake would be indistinguishable from the mistake.
- 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/edit-discipline.md`

# Edit Discipline & Reviewable Changes

## Edit files with the editing tools, not the shell

Use the `edit` and `write` tools to change a file. Do not rewrite tracked files
through `bash` with `sed`, `awk`, `tee`, a heredoc, or `>` redirection.

This is not a style preference. A shell rewrite is opaque to the host: the
session records a command, not a change. An `edit` call records which file
changed and how, so the interface can render it, a reviewer can read it, and a
later turn can cite it. A `sed` line records none of that, and the only way to
find out what happened is to read the file again.

The shell remains correct for what it is for: running builds, tests, linters,
git, package managers, and generators that own their own output.

## Show the change before calling the work done

Before reporting a file-changing task as finished, show what changed:

```bash
git diff -- <paths>          # tracked files
git status --short           # what is new or removed
```

Paste the diff into the reply, or state precisely why it is too large and
summarise it by file with the counts. A task that reports success without
showing the change asks the reader to take the result on trust, and the reader
is the one who has to decide whether to commit it.

For an untracked file, show the content you wrote, not a description of it.

## Why both halves matter together

Editing through the tools makes a change *recordable*; showing the diff makes it
*reviewed*. Either alone leaves the person deciding whether to ship blind to
something they are accountable for.

## 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](https://protobuf.dev/programming-guides/style/) (mandatory), [Google AIP-126 / api-linter](https://linter.aip.dev/126/upper-snake-values) (enforced), [Zalando Rule #240](https://opensource.zalando.com/restful-api-guidelines/), 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-team.md`

# Git Team Workflow Rules

These rules assume more than one person merges into `main`. They ship only with
the `strict` profile; a solo maintainer who commits straight to `main` is not
doing anything wrong, and a reviewer that keeps flagging "use a feature branch"
in that setting is noise. The solo-safe core (commit format, no secrets, no
force-push) lives in `git-workflow`.

## Branching
- Protect `main` with required reviews and CI. Never commit broken code to it.
- Work on feature branches: `feat/user-registration`, `fix/order-total-calc`.
- Rebase feature branches on `main` before opening a PR to keep linear history.
- Squash fixup commits before merging to keep history clean.
- Delete branches after merge. Stale branches are clutter.

## 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.

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

# Git Workflow Rules

Solo-safe core: everything here holds whether one person or twenty merge into
`main`. Branching, pull-request, and review conventions for teams live in
`git-team` and ship only with the `strict` profile.

## 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.
- `main` is always deployable: run the project's gates before every commit that lands there.

## 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 safe, actionable messages for known failures; use a neutral fallback when the cause is unknown or disclosure would reveal protected information.
- Keep SQL, stack traces and provider internals out of ordinary client responses, including 4xx and background-job error fields. Preserve original causes in access-controlled, redacted diagnostics.
- 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).
- Run integration suites serially when they share or reset a database. Parallel runners need isolated databases/stores; a filtered test must not invalidate an in-progress full suite.

## API Error Paths
- For changed error handling, assert the actual status, public code/message, field paths, locale and recovery headers through the API boundary.
- Preserve JSON object/list types, including empty nested `{}` and `[]`, when testing response filters.
- Exercise real database constraints, idempotent replay and known versus uncertain write outcomes; schema-generated fixtures may omit migration-only indexes.

## 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).