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:

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