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