Make the AI behave like the 15-year senior who has to maintain this in a year —
not the Tactical Tornado who's moving on tomorrow.

→ See the live site ←

Why · How it works · What it catches · The 9 skills · The 13 rules · Install on any tool · Live site

---

Why this exists

Working code is not the bar. Code the next person can read, trust, and change is the bar.

Basic prompts and AI tools produce code with a short shelf life — it works in the demo, then needs reworking in two weeks. That isn't a vibe; it's measured:

The core diagnosis: an AI coding agent is a "Tactical Tornado" (Ousterhout) — fast, prolific, leaving a maintenance wake. Worse, it spends complexity in the wrong place: over-building structure while skipping robustness at the boundaries. craft reverses both. Every skill forces strategic (durable) code over tactical (fast-but-disposable) code, and where two approaches both work, it picks the one that leaves the system Easier To Change.

---

How it works

craft sits between your agent and "done." The production-grade router reads the change, fires only the skills that apply, and nothing ships until the work is proven — while building (skills steer the agent as it writes, so the strategic version comes out first) or as a gate after (/senior-review, the Copilot port, or a CI check blocks the merge). Want it interactive? The live site animates the same flow.

---

Architecture

craft skills detect and judge; they route the mechanical fix to the analysis skills you already have — no duplication.

flowchart LR
    PR["diff / pull request"] --> ROUTER{{"production-grade<br/>router"}}

    subgraph DETECT["craft · detect + judge"]
        direction TB
        RSD["right-sized-design"]:::g
        RB["robustness-at-boundaries"]:::g
        DRY["dry-and-reuse"]:::g
        TT["trustworthy-tests"]:::g
        CS["code-smells"]:::t
        EP["effects-and-purity"]:::t
        NC["naming-and-comments"]:::t
        SC["supply-chain-hygiene"]:::t
    end

    ROUTER --> DETECT
    DETECT --> FIX["refactoring-patterns<br/>complexity-analysis<br/>dependency-analyzer"]:::e
    FIX --> V{"SHIP · SHIP-WITH-FIXES · REWORK"}:::v

    classDef g fill:#1A1410,stroke:#E3B341,color:#E3B341;
    classDef t fill:#0E1A19,stroke:#39C5BB,color:#39C5BB;
    classDef e fill:#10141B,stroke:#58A6FF,color:#9Fc6ff;
    classDef v fill:#1A1010,stroke:#F85149,color:#FF9C94;

Loading

Two modes from the router (production-grade):

• Generative guard — invoked while building: load the right senior heuristics before the code is written, so it's born right instead of fixed later.
• Critique — invoked on a diff/PR: return one worst-first, principle-tagged list with the fix for each finding (severity = job-damage × fix-cheapness), plus a Definition-of-Done check.

---

What it catches

Six real failure modes, before & after — explore them interactively on the live site → (click any case to flip slop ↔ craft). Each names the rule it enforced.

Failure mode	Without craft	craft enforces	Skill
Over-engineering	a factory + interface for exactly one user	smallest diff; no abstraction without 2–3 call sites	right-sized-design
Swallowed errors	a 404 returned as a "user"; catch {} → {}	check status, validate the shape, fail loud	robustness-at-boundaries
Hallucinated deps	import requesocks — a typosquat that doesn't exist	verify on the registry before it hits the lockfile	supply-chain-hygiene
Duplication	the 4th hand-rolled slugify, subtly wrong	grep first; reuse the one shared source	dry-and-reuse
Fake-green tests	expect(mock).toBe(...) — green forever, proves nothing	assert observable behavior against a real fake	trustworthy-tests
Logic ⊗ I/O	the discount rule buried between DB calls and Stripe	pure core, imperative shell — trivially testable	effects-and-purity

The one most reviewers miss — a dependency that simply does not exist (~19.7% of AI-suggested packages don't; USENIX Security 2025):

- import requesocks                  # typosquat of "requests" — not a real package
- from datetime_utils import parse   # invented module that just looks plausible
+ from datetime import datetime      # stdlib; verified, canonical
+ import requests                    # the real client, confirmed on PyPI

---

The nine skills

Tier-1 are the 80/20 — the four that attack the most-documented failure mechanisms. Click to expand.

🪓 right-sized-design  ·  anti-over-engineering / YAGNI / deep modules  tier-1

Catches the #1 AI failure: factories, interfaces, and config "just in case." No abstraction until it has ≥2–3 real call sites; deep modules over shallow; smallest diff that satisfies the request.

- class DiscountStrategyFactory { /* +interface +manager, 4 files, 1 use */ }
+ function applyDiscount(total, pctOff) {            // one validated function
+   if (pctOff < 0 || pctOff > 100) throw new RangeError(`0–100, got ${pctOff}`);
+   return total * (1 - pctOff / 100);
+ }

🛡️ robustness-at-boundaries  ·  validate edges · never swallow errors · secrets  tier-1

Catches the #1 AI omission: validation and error handling exactly where production breaks. Validate at the boundary, once; never catch {} into silence; define errors out of existence; no hardcoded secrets.

- def create_user(body: dict):
-     user = User(email=body["email"], role=body.get("role", "admin"))  # insecure default
-     try: send_welcome(user); 
-     except Exception: pass                                            # swallowed
+ def create_user(req: CreateUserRequest):   # pydantic validates at the edge → 422 on bad input
+     user = User(email=req.email, role=req.role)  # safe typed default
+     try: send_welcome(user)
+     except EmailServiceError as e: log.warning(...); enqueue_retry(...)  # visible, degrades

♻️ dry-and-reuse  ·  search-before-build · consolidate-don't-clone  tier-1

Catches the duplication GitClear measures as "rework." DRY is about knowledge (one rule, one home), not incidental look-alikes. Search the repo/stdlib before writing a util; extract instead of copy-paste.

✅ trustworthy-tests  ·  no fake tests · prove it ran  tier-1

Catches tautological tests (asserting on their own mocks), implementation-mirroring, and "done" claimed without ever running the code. Test observable behavior; pin untested code with a characterization test before refactoring; show evidence it ran.

- expect(spy).toHaveBeenCalled();        // proves only that we called it
+ expect(checkout({total:200}, "SAVE10").total).toBe(180);   // fails if the math is wrong

👃 code-smells  ·  Fowler's catalog as a detection lens

Names the smell, states the change-cost, and routes the fix to refactoring-patterns. Ranks by job-damage × fix-cheapness — Change Preventers (Shotgun Surgery, Divergent Change) outrank cosmetics. The two AI-signature smells: Duplicate Code and Speculative Generality.

⚗️ effects-and-purity  ·  functional core, imperative shell (pragmatic)

Isolate side effects at the boundary; keep decision logic pure so it's testable without heavy mocks. Balanced, not dogmatic — it does not ban mutation or demand monads. Inject the clock/RNG/clients instead of calling them inline.

🔤 naming-and-comments  ·  intent-revealing names · comments carry why

Vague names (data, tmp, Manager) and comments that restate the code are slop. Names carry intent; comments carry rationale, units, invariants. If a name is hard to pick, the design is unclear.

📦 supply-chain-hygiene  ·  verify deps exist · no hallucinated APIs

~20% of AI-suggested packages don't exist (slopsquatting — attackers pre-register the recurring hallucinated names). Verify every dependency is real and canonical before install; don't call methods/fields that aren't in the real API; never inline secrets.

🗄️ data-and-state-evolution  ·  expand→migrate→contract · safe schema changes

Catches the slop a diff can't show: a migration that's fine on dev and locks a 10M-row table in prod, a renamed column that 500s the old code still running mid-deploy, a backfill with no rollback. Every persistent-shape change ships in phases — expand, migrate, contract — with a dry-run on a copy as evidence.

- ALTER TABLE users RENAME COLUMN username TO handle;   -- breaks every running instance
+ ALTER TABLE users ADD COLUMN handle TEXT;             -- 1. expand (additive, safe)
+ -- 2. code writes both / reads either · batched backfill · 3. contract later

---

The 13 rules

The always-on constitution (RULES.md) — drop it into your repo's CLAUDE.md / AGENTS.md / .cursorrules:

#	Rule	#	Rule
1	Smallest change that satisfies the request	7	Pure logic; quarantine side effects at the edges
2	No abstraction without ≥2–3 real call sites	8	Clear beats clever
3	Search before you build	9	Names carry intent; comments carry why
4	Consolidate, don't clone	10	No tautological tests; prove it ran
5	Match the codebase, not your defaults	11	Pin untested code before refactoring
6	Validate at the boundary; never swallow errors	12	Verify every dependency; never hardcode secrets
		13	Data outlives code: expand → migrate → contract

…closed by a Definition of Done that requires "I ran it — here's the evidence", a test seen red before green, and a dry-run for every migration.

Three-tier instructions

Each skill is layered so context is spent only when needed:

SKILL.md reflex card (heuristics + red flags, always-on) → references/ playbook (the book-grounded rationale, on demand) → examples/ worked before/after (slop-vs-senior code).

---

Also runs in GitHub Copilot

dist/github-copilot/ ports the same guardrails to Copilot (with GPT or any model), so the whole team is covered:

• copilot-instructions.md — the 13 rules; honored by completions, chat, and Copilot's PR review, on every IDE.
• instructions/*.instructions.md — path-triggered per-topic guidance (the 9 skills + Python/TypeScript/Go tells).
• prompts/senior-review.prompt.md — /senior-review in Copilot Chat.

The port trades fidelity for portability (no intent-based auto-trigger, no hooks), so lean on CI + Copilot PR review for enforcement. Rules-as-prose get ~25–40% compliance; mechanical gates reach ~95%.

---

Install — any agentic tool

One constitution (RULES.md), every platform. Pick your tool, copy one command (hover any block on GitHub for the copy button), commit. Same rules everywhere — adopt on one repo or roll out to a whole class.

Claude Code — native plugin: 9 skills + a router auto-load, plus the /senior-review gate

git clone https://github.com/manutej/craft ~/.claude/plugins/craft

Then run /senior-review <file|dir|PR#> on any diff, or call a skill directly — e.g. craft:right-sized-design.

Cursor — Project Rule, always applied across chat, ⌘K edits, and Composer

mkdir -p .cursor/rules
curl -fsSL https://raw.githubusercontent.com/manutej/craft/main/dist/cursor/craft.mdc -o .cursor/rules/craft.mdc

Legacy Cursor (single file): curl -fsSL https://raw.githubusercontent.com/manutej/craft/main/RULES.md -o .cursorrules

GitHub Copilot — completions, chat, and automated PR review

mkdir -p .github
curl -fsSL https://raw.githubusercontent.com/manutej/craft/main/RULES.md -o .github/copilot-instructions.md

Richer port (per-language rules + a /senior-review prompt): dist/github-copilot/.

Windsurf — Cascade rules, every session

curl -fsSL https://raw.githubusercontent.com/manutej/craft/main/RULES.md -o .windsurfrules

Cline / Roo Code — workspace rules, every task

curl -fsSL https://raw.githubusercontent.com/manutej/craft/main/RULES.md -o .clinerules

Codex · AGENTS.md — the cross-tool standard (Codex, Jules, Gemini CLI…)

curl -fsSL https://raw.githubusercontent.com/manutej/craft/main/RULES.md -o AGENTS.md

One file, many agents — the most portable way to ship the rules to a team.

Aider — conventions passed on every request

curl -fsSL https://raw.githubusercontent.com/manutej/craft/main/RULES.md -o CONVENTIONS.md

Then add to .aider.conf.yml: read: CONVENTIONS.md

The Cursor .mdc is generated from RULES.md by scripts/gen-ports.py — one source of truth, no clones (craft eats its own rule #4). Every other platform reads RULES.md directly.

craft/
├── RULES.md                     # always-on constitution — the single source
├── commands/senior-review.md    # the /senior-review gate
├── skills/                      # production-grade (router) + 8 guardrails
├── references/                  # PRINCIPLES · SMELLS · EVIDENCE · lang/*
├── dist/cursor/                 # generated Cursor .mdc port
├── dist/github-copilot/         # the Copilot port (per-language + PR review)
└── dist/ci/                     # mechanical enforcement: CI gate + Copilot-review setup

Enforcement — make the rules a hard stop

Rules raise the floor; gates change behavior (~40% → ~95% compliance). dist/ci/ ships a copy-paste senior-gate.yml (run your lint + type-check + tests as a required check) and a guide to enabling Copilot's automated PR review against the shipped rules. This repo dogfoods the idea: its own validate workflow checks the manifest, skill frontmatter, SVGs, and links on every push.

---

Composes with

craft detects and judges; it hands the mechanics to the analysis skills you already run: refactoring-patterns (apply the fix), complexity-analysis / complexity-metrics (quantify), dependency-analyzer (coupling), test-coverage-analyzer (coverage). Nothing is duplicated.

Sources

The Pragmatic Programmer (Hunt & Thomas) · Refactoring (Fowler & Beck) · A Philosophy of Software Design (Ousterhout) · The Grug Brained Developer (Gross) · Working Effectively with Legacy Code (Feathers) · The Twelve-Factor App · Functional Core / Imperative Shell (Bernhardt) · GitClear, Stanford & USENIX empirical studies. Condensed in references/.

Built by CETI — Center for Educational Technology Innovations.

_{craft · v0.1.0 · stable · sustainable · production-grade}