/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 comm