craft

Makes schema, migration, and data-shape changes safe to ship. Use when writing a database migration, altering a table, adding/renaming/dropping a column, changing the shape of an API payload / event / serialized object, backfilling data, or reviewing any diff that touches persistent state. Catches one-shot breaking changes, NOT NULL without backfill, missing/untested rollbacks, nullability drift, and backfills that lock production tables. Enforces expand→migrate→ contract, one-deploy-window backward compatibility, and dry-run-on-a-copy evidence. Triggers: "write a migration", "alter table", "add a column", "rename this field", "change the schema", "is this migration safe", "change this response/event shape", "backfill".

Router and orchestrator for the craft code-quality guardrails. Use FIRST on any broad "is this production-ready?", "review this code/diff/PR", "build this properly", "why does our AI-generated code keep needing rework", or "make this maintainable" request. Two modes: GENERATIVE GUARD (load the right senior heuristics before writing code) and CRITIQUE (audit a diff/file and return one worst-first ranked list of findings). Decomposes the request, fires the relevant craft member skills plus the existing complexity/refactoring/dependency/test skills in the right order, resolves their conflicts, and returns a single merged verdict. Defer to a single member skill only when the task is already narrow.

Makes tests prove something and makes "done" mean done. Use when writing tests, judging existing tests, or before claiming a task is complete/production-ready. Catches tautological tests (asserting on their own mocks), tests that mirror the implementation, fake green CI, and the agent's habit of declaring victory without ever running the code. Enforces test-observable-behavior, the verification-before- done evidence gate, and characterization-tests-before-refactoring-untested-code. Triggers: "write tests for this", "are these tests any good", "is this done", "is it production-ready", "add coverage", before any "done"/handoff claim.

Detection lens for Fowler's five smell families — names the smell, states the change-cost, and hands the fix to `refactoring-patterns`. Use when reviewing a diff, auditing a module, or deciding whether to gate a merge. Triggers: "does this code have smells", "review for smells", "is this clean", "what's wrong with this design", "this class is getting big", "why is every change touching 12 files", "switch on type", "this method is too long", "is this AI slop".

Stops duplication and reinvention — the failure GitClear measures as "rework" (copy-paste up, refactoring down, the signature of AI code with a short shelf life). Use before writing any helper, util, type, constant, or component, and when reviewing a diff for repeated logic. Enforces search-before-build, consolidate- don't-clone, and DRY-as-knowledge (one rule, one authoritative place). Triggers: "is there already a function for this", "this looks duplicated", "DRY this up", "extract the common logic", "we keep rewriting this", before adding any utility.

Separates pure decision logic from I/O so code is testable without heavy mocks — without demanding religious purity. Use when a function both computes and writes to a DB, network, or log; when datetime.now()/random()/fetch() are called inline inside business logic; when a unit test needs five mocks to run; when reviewing code that tangles "what to do" with "do it." Triggers: "this is hard to test," "I need to mock the clock," "how do I test this without a DB," "pure function," "side effects," "functional core," "inject the dependency." NOT a trigger for: making everything pure, banning mutation, or wrapping simple code in monads.

Names and comments are the primary channel through which code communicates intent to the next engineer. Use when choosing an identifier ("what should I call this", "rename this", "is this name clear"), deciding whether to add a comment ("should I comment this", "does this need explaining"), or auditing existing prose ("clean up the comments", "too many comments", "comment slop"). Also fires when a name is hard to pick — that difficulty is a design smell, not a vocabulary problem (Ousterhout: Hard to Pick Name).

Fights over-engineering and premature abstraction — the #1 documented AI coding failure. Use when about to add a class, interface, factory, base-class, config layer, plugin system, generic "framework," or any abstraction; when a diff feels bigger than the request; or when reviewing code that has more structure than the problem warrants. Enforces smallest-diff-that-works, YAGNI, "no abstraction without 2-3 real call sites," and Ousterhout's deep-vs-shallow-module test. Triggers: "is this over-engineered", "simplify this", "do we need this abstraction", "this feels heavy", "make it production-ready" (often means add-robustness-not-structure).

The robustness the AI skips. Use whenever code reads untrusted input (API request, user input, file, env, parsed JSON, DB row, external response), handles errors, or touches secrets/config. Enforces validate-at-the-edge, never-swallow-errors, define-errors-out-of-existence, no-hardcoded-secrets, and meaningful error contracts. Counters the #1 AI omission: agents over-build structure but skip input validation and error handling exactly where production breaks. Triggers: "add error handling", "validate this input", "handle the edge cases", "is this safe", "production hardening", any try/catch, any parse/deserialize, any API handler.

The verification gate AI agents skip. Use whenever you add a dependency, ask "is this package safe", import a library, call an external API, pin versions, or check a package exists. Catches hallucinated packages (19.7% of AI suggestions, USENIX 2025), hallucinated APIs, typosquats, and inlined secrets before they reach the codebase. Triggers: "add a dependency", "is this package safe", "import this library", "call this API", "pin versions", "check this package exists", any new third-party import.