claude-code-standards-kit

Claude Code Standards Kit

Professional standards for Claude Code — grounded in science, not opinions.

Designed and maintained by SQWR Studio (branding & design) and Flows Studio (automation & agentic development)

---

A solo developer with Claude Code can write code. But does that code comply with OWASP? WCAG 2.1? Core Web Vitals? AWS Well-Architected standards?

Most of the time: no. Not for lack of talent — for lack of method.

The kit provides measurable, threshold-based standards for each domain. Projects that apply these standards consistently reach ≥85/100 when audited against them — the same standards the kit applies to itself.

Run bash scripts/verify-kit.sh --verbose to see the kit score its own components.

Professional quality is not in the code — it is in the research that precedes the code.

---

Quick start

Requirements: jq and node are required, not optional. jq is enforced by the installer (it exits if missing); node runs global/hooks/validate-command.js, the main destructive-command guard, and without it that guard is silently inactive. bash and python3 are also used by several hooks and scripts. rtk is the only genuinely optional tool (its hook is a no-op without it).

# One-command install
curl -sL https://raw.githubusercontent.com/samsam007b/claude-code-standards-kit/main/scripts/install.sh | bash

curl | bash runs a remote script sight-unseen. If that is not acceptable for your setup, clone a tagged release and read scripts/install.sh before running it:

git clone --branch v4.1.0 --depth 1 https://github.com/samsam007b/claude-code-standards-kit ~/sqwr-standards-kit
less ~/sqwr-standards-kit/scripts/install.sh   # read it
bash ~/sqwr-standards-kit/scripts/install.sh    # run it once you are satisfied

There is no code-signing or checksum to verify here (the kit does not publish one); cloning a pinned tag and reading the script first is the verifiable alternative to piping an unread stream into a shell.

Or manually:

# 1. Clone the kit
git clone https://github.com/samsam007b/claude-code-standards-kit ~/sqwr-standards-kit

# 2. Bootstrap a new project (plugin mode — recommended)
bash ~/sqwr-standards-kit/scripts/init-project.sh \
  --name "my-project" --stack "nextjs-supabase" --path "~/Desktop/my-project" --plugin

# 3. Verify kit integrity
bash ~/sqwr-standards-kit/scripts/verify-kit.sh --verbose

# 4. Verify project health
bash ~/sqwr-standards-kit/scripts/verify-project.sh --path ~/Desktop/my-project

New in v4: the user-level layer. Install the hooks, scripts, skills, commands, agents and global CLAUDE.md that run a full-time Claude Code setup into ~/.claude:

bash ~/sqwr-standards-kit/global/install-global.sh --dry-run   # preview
bash ~/sqwr-standards-kit/global/install-global.sh             # install (backs up, never overwrites without --force)

See Two layers below.

Available stacks: nextjs-supabase · nextjs · nextjs-supabase-ai · python · ios · android · fullstack

Which stack should I choose?

You are building...	Stack
SaaS web app with auth + database	nextjs-supabase
Marketing site or static content	nextjs
AI-powered product (chatbot, copilot, RAG)	nextjs-supabase-ai
Backend API or data pipeline	python
Native iPhone / iPad app	ios
Native Android app	android
Full platform — all 40 contract domains	fullstack

---

Two layers: project plugin + user-level setup

The kit has two layers that install independently.

Layer	Where it installs	What it governs
Project plugin (contracts/, audits/, agents/, skills/, hooks/)	the project's .claude/ or as a plugin	Quality of what you ship: thresholds, audits, scoring
User-level setup (global/)	~/.claude/	How Claude Code itself behaves in every project: safety, cost, memory, session hygiene

What the user-level layer contains

Component	Count	Highlights
Global CLAUDE.md	1	Self-verification before the final answer, output and context discipline, 2-phase research, CLI over MCP, model delegation (opusplan by default), routing measured by real usage, "just content" communication style. Every rule carries its Why.
Hooks	18	Destructive-command blocker, external-send guard (email/social needs a confirmation typed in the current turn), "never a small model for code" gate, force-push and generated-file guards, marketplace and plugin vetting (allowlist + human confirmation + tamper guard), memory novelty gate, Stop hook against uncertainty without a local search, RTK rewrite with integrity check, session lifecycle (pre-compact save, session-end capture, memory context load). See global/hooks/README.md.
Scripts	17	env-vault (age-encrypted .env), secret scanning, worktree helpers, heartbeat watchdog with a canary on the alert channel itself, cost status line and dashboard, skill/agent usage scan, log and file-history rotation. See global/scripts/README.md.
Skills	5	engineering-philosophy, just-content, anti-ai-writing, marketplace-vetting, pre-design
Commands	5	/grill, /clean-commit, /opusplan, /fableplan, /audit-drift
Agents	7	researcher and doc-reader (Haiku, 400-token digests), code-reviewer, debug-assistant, test-writer, pr-describer, memory-sync
Docs	3	docs/MEMORY-SYSTEM.md, docs/SKILLS-GOVERNANCE.md, docs/TEAM-MANAGED-SETTINGS.md

Design principles of this layer:

• Hooks over prose. A rule that matters is enforced by a hook; prose is forgotten under load.
• Fail-open by default, fail-closed for security guards. A broken helper never blocks your work, a broken security guard never lets a risky action through.
• Measure before you promise. Routing rules and skills that never fire are archived (see docs/SKILLS-GOVERNANCE.md).
• Tested. bash ~/.claude/hooks/tests/smoke-test-hooks.sh and bash ~/.claude/hooks/tests/test-marketplace-vetting.sh run in a sandbox.

---

How it works

  RESEARCH   →  CONTRACT  →  CODE  →  AUDIT

  "What are     Rules +      Claude Code   Score /100
  the pro       thresholds   follows the   per domain
  standards     + cited      contract      (≥85 target)
  on this       sources
  topic?"

Claude Code does not start from opinions. It looks up existing standards, synthesises them into actionable rules, then applies them. This kit structures that workflow across 40 contract domains.

Read METHODOLOGY.md for the full method.

---

What is included

Category	Files	Role
Contracts	40	Business rules with numerical thresholds — copy into CLAUDE.md
Frameworks	13	Situational tools (branding, estimation, incident, campaign…)
Audits	14	Scoring /100 per domain — run before each delivery
Agents	14	Automated audit agents + Haiku research subagents — place in .claude/agents/
Skills	10	Slash-command workflows — /new-feature, /brainstorm, /pre-deployment, /monthly-review, /audit-runner, /contract-lookup, /project-setup, /auto-fix, /compliance-check, /risk-score
Commands	4	Slash commands — /init-project, /full-audit, /verify-kit, /verify-project
Hooks	22	Claude Code compliance hooks — enforcement + session management + token economy monitoring (22 hook scripts)
Workflows	3	Structured process templates (RESEARCH → CONTRACT → CODE → AUDIT)
Templates	7	CLAUDE.md, settings.json, .claudeignore, rtk-filters.toml, CHANGELOG.md, CONTRIBUTING.md, github-actions/verify-kit.yml
Scripts	5	install.sh, init-project.sh, verify-kit.sh, verify-project.sh, validate-claude-md.sh

---

Scientific Validation

The SQWR Project-Kit's contract-based approach is formally validated by peer-reviewed research:

Paper	Finding	Source
arXiv 2601.08815	Contract-based prompting reduces token usage by 90% in LLM-assisted development	arXiv, 2025
arXiv 2602.22302	Structured contracts achieve 86% success rate vs 70% baseline for complex development tasks	arXiv, 2025

These papers independently validate the core hypothesis: structured, sourced contracts outperform ad-hoc prompting both in efficiency and quality.

---

The contracts

Every rule has a numerical threshold. Every threshold has a verifiable source.

Contract	Domain	Standard
CONTRACT-NEXTJS.md	App Router, SSR, CWV	Google Core Web Vitals
CONTRACT-SUPABASE.md	Database, RLS, auth	NIST SP 800-63B
CONTRACT-VERCEL.md	Deployment, rollback, canary	Vercel docs + Martin Fowler
CONTRACT-DESIGN.md	Gestalt, typography, colour	Itten, Bringhurst, WCAG 2.1
CONTRACT-TYPESCRIPT.md	TypeScript strict, SOLID	Robert C. Martin
CONTRACT-TESTING.md	Test pyramid, coverage	Martin Fowler, Agile Alliance
CONTRACT-SECURITY.md	OWASP Top 10, secrets, XSS	OWASP, NIST, CWE Top 25
CONTRACT-PERFORMANCE.md	LCP, INP, CLS, Lighthouse	Google, DebugBear
CONTRACT-ACCESSIBILITY.md	WCAG 2.1 AA + EAA (EU law)	W3C, Nielsen NN/G
CONTRACT-ANTI-HALLUCINATION.md	Real data, RAG, context poisoning	Nature 2025, OpenAI
CONTRACT-AI-PROMPTING.md	System prompts, few-shot, models	Anthropic, Lakera
CONTRACT-OBSERVABILITY.md	Structured logging, Sentry, RUM	Google SRE Book
CONTRACT-RESILIENCE.md	Retry, circuit breaker, graceful degradation	AWS Well-Architected
CONTRACT-GREEN-SOFTWARE.md	Carbon impact, SCI	ISO/IEC 21031:2024
CONTRACT-PYTHON.md	PEP 8, mypy, FastAPI, packaging	PEP standards, Python.org
CONTRACT-IOS.md	SwiftUI, touch targets, Dark Mode	Apple HIG, WCAG 2.5.5
CONTRACT-PDF-GENERATION.md	Puppeteer, react-pdf, CSS Paged Media	W3C CSS Paged Media, pptr.dev
CONTRACT-SEO.md	SSR, metadata, JSON-LD, Core Web Vitals	Google Search Central, schema.org
CONTRACT-EMAIL.md	SPF/DKIM/DMARC, React Email, deliverability	RFC 7489, Google Sender Guidelines 2024
CONTRACT-CICD.md	GitHub Actions, DORA, branches, Conventional Commits	DORA Research, semver.org
CONTRACT-ANALYTICS.md	HEART, AARRR, GA4, PostHog, event taxonomy	Google CHI 2010, Dave McClure 2007
CONTRACT-I18N.md	next-intl, ICU, hreflang, RTL, Intl API	Unicode CLDR, W3C i18n
CONTRACT-PRICING.md	Van Westendorp, EVC, SaaS metrics, tiers	ESOMAR 1976, ProfitWell, SaaStr
CONTRACT-ANDROID.md	Jetpack Compose, Material 3, TalkBack, Vitals	Android Developers, m3.material.io
CONTRACT-MOTION-DESIGN.md	UI animation, Remotion, easing, prefers-reduced-motion	Material Design 3, Apple HIG, W3C WCAG 2.3
CONTRACT-VIDEO-PRODUCTION.md	Video pipeline, platform export, ElevenLabs, AI studio	Instagram/TikTok/YouTube specs, NN/G
CONTRACT-API-DESIGN.md	REST/GraphQL design, versioning, rate limiting	RFC 7231, OpenAPI 3.1.0, OWASP API Security
CONTRACT-DATABASE-MIGRATIONS.md	Schema evolution, zero-downtime, rollback	Fowler 2016, PostgreSQL, AWS Well-Architected
CONTRACT-ERROR-HANDLING.md	Error boundaries, user messages, retry	Nielsen NN/G, Google SRE Book, React docs
CONTRACT-AI-AGENTS.md	AI Agents & Tool Calling	Anthropic, OpenAI, LangChain docs
CONTRACT-GRAPHQL.md	GraphQL API	GraphQL spec, Apollo docs, OWASP API Security
CONTRACT-MULTI-TENANT.md	Multi-Tenant Architecture	AWS Well-Architected, NIST
CONTRACT-FEATURE-FLAGS.md	Feature Flags	Martin Fowler, LaunchDarkly docs
CONTRACT-MONOREPO.md	Monorepo	Nx, Turborepo, Google monorepo research
CONTRACT-DOCUMENTATION.md	Documentation	Divio documentation system, Google dev docs
CONTRACT-EU-AI-ACT.md	EU AI Act Compliance	EU Regulation 2024/1689, NIST AI RMF, ISO/IEC 42001
CONTRACT-AI-SAFETY.md	AI Safety & Agentic Security	OWASP Agentic AI Top 10 2025, NIST AI 600-1
CONTRACT-DORA-METRICS.md	DORA DevOps Metrics	DORA State of DevOps 2024, Accelerate (Forsgren et al.)
CONTRACT-ANTI-PATTERNS.md	AI Coding Anti-Patterns	Fowler (2018), Martin (2008), OWASP Agentic AI 2025, DORA 2024
CONTRACT-TOKEN-ECONOMY.md	Token Economy & Cost Optimization	Anthropic Pricing 2025, arXiv 2601.08815, Empirical (3.2x validated)

---

The audit system

Score /100 before each delivery. Delivery threshold: ≥85/100 overall.

Audit	Weight	Blocking
AUDIT-SECURITY.md	22%	< 70 = blocking
AUDIT-PERFORMANCE.md	18%	< 70 recommended
AUDIT-CODE-QUALITY.md	18%	< 75 recommended
AUDIT-OBSERVABILITY.md	12%	< 60 recommended
AUDIT-ACCESSIBILITY.md	12%	< 80 + EU legal
AUDIT-DESIGN.md	8%	< 70 recommended
AUDIT-AI-GOVERNANCE.md	5%	< 80 recommended
AUDIT-DEPLOYMENT.md	5%	Pre-production gate
AUDIT-RGPD.md	—	≥80/100 before public prod
AUDIT-BRAND-STRATEGY.md	—	Before launch or repositioning
AUDIT-RESILIENCE.md	— (supplementary)	≥70 recommended for production systems

See audits/AUDIT-INDEX.md for the sequencing.

---

Automation layer

Standards that enforce themselves.

The kit ships with a Claude Code–native automation layer inspired by GSD — active enforcement, not passive checklists.

Component	Count	What it does
Plugin manifest	1	.claude-plugin/plugin.json (v4.1.0) — auto-discovers agents, skills, hooks, commands
Audit agents	11	Run agents/AGENT-SECURITY-AUDIT.md — 4-level verification with enriched frontmatter (model, effort, color)
Skills	10	/brainstorm, /new-feature, /pre-deployment, /monthly-review, /audit-runner, /contract-lookup, /project-setup, /auto-fix, /compliance-check, /risk-score
Slash commands	4	/init-project, /full-audit, /verify-kit, /verify-project
Compliance hooks	22	hooks/hooks.json — 22 hook scripts: secrets, build, XSS, contract compliance, session context, post-response, session-end, and more
Workflow templates	3	WORKFLOW-NEW-FEATURE.md — 5 gates with Observable Truths

init-project.sh provisions:

• .claude/settings.json (legacy) or .claude/hooks.json (with --plugin)
• .claude/agents/ with all 11 audit agents
• .claude/skills/ and .claude/commands/ (with --plugin)
• docs/audits/ with stack-relevant audit files

---

Skills (9)

Skill	Usage	Description
Brainstorm	/brainstorm <task>	Pre-implementation guard — scope + reversibility + approach plurality before first line of code
New Feature	/new-feature <description>	Full RESEARCH → CONTRACT → CODE → AUDIT workflow
Audit Runner	/audit-runner <domain>	Run one or all SQWR audit agents
Pre-Deployment	/pre-deployment	Full quality gate before merging to main
Monthly Review	/monthly-review	Complete monthly audit cycle
Contract Lookup	/contract-lookup <domain>	Find applicable contracts for a task
Project Setup	/project-setup <stack>	Bootstrap a new project with SQWR standards
Auto Fix	/auto-fix	Automatically fix console.log, alt text, TODO format
Compliance Check	/compliance-check <regulation>	EU regulatory compliance (EAA, GDPR, AI Act)
Risk Score	/risk-score [quick|full]	Compute composite SQWR Risk Score (0-100)

---

Positionnement

Dans l'écosystème des outils communautaires pour Claude Code, trois projets couvrent des besoins voisins mais distincts : davila7/claude-code-templates (32k+ étoiles) est un CLI de configuration et de monitoring, avec un catalogue de templates et un dashboard d'analytics. SuperClaude-Org/SuperClaude_Framework (23k+ étoiles) ajoute des commandes spécialisées, des "personas" cognitives et des méthodologies de développement. get-shit-done par TÂCHES (64k+ étoiles, qui a inspiré la couche d'automatisation de ce kit, voir plus haut) propose un système de meta-prompting et de développement piloté par les specs.

Ce kit se positionne différemment : ce n'est pas un gestionnaire de templates, un système de personas, ou une méthodologie de planification, mais un corpus de standards vérifiables. Chaque contrat (contracts/) cite une source Tier 1 ou Tier 2 (OWASP, WCAG, NIST, Nielsen NN/G...) et porte un seuil numérique ; chaque audit (audits/) transforme ces seuils en score sur 100 ; les hooks (hooks/, global/hooks/) et scripts/verify-kit.sh font respecter ces seuils de façon automatique plutôt que déclarative. Les chiffres exacts (contrats, audits, agents, hooks, scripts, skills) sont listés dans les tableaux ci-dessus et recomptés à chaque exécution de verify-kit.sh.

---

Why this kit?

What sets it apart from all other starter kits:

1. Numerical thresholds, not opinions "LCP ≤2.5s (p75)" — not "good performance". Every rule is measurable.

2. Mandatory Tier 1/2 sources OWASP, WCAG, Google SRE, NIST, Nielsen NN/G, W3C. No "it is recommended to".

3. Brand strategy included frameworks/BRAND-STRATEGY.md covers Sinek, Jung, StoryBrand, Blue Ocean. Absent from 99% of technical starter kits.

4. Built-in EU legal compliance EAA (active since June 2025), EU AI Act, GDPR. See frameworks/COMPLIANCE-EU.md.

5. The kit applies itself bash scripts/verify-kit.sh --verbose runs the kit's own integrity checks (file presence, sourced contracts, numeric thresholds, number drift between README and the filesystem) and must report 0 errors. The GitHub Actions badge above runs the same check on every push.

6. Active enforcement, not passive checklists 11 audit agents, 22 compliance hook scripts, 3 workflow templates. Standards that are checked automatically, not discovered in post-mortems.

7. The only kit with API design + database migrations + error handling standards in one place CONTRACT-API-DESIGN.md (RFC 7231, OpenAPI 3.1.0), CONTRACT-DATABASE-MIGRATIONS.md (Fowler Expand-Contract, PostgreSQL), and CONTRACT-ERROR-HANDLING.md (Nielsen NN/G, Google SRE) cover the three most common sources of silent production failures.

8. Uniquely includes brand strategy and EU legal compliance frameworks/BRAND-STRATEGY.md (Sinek, Jung, Miller) and frameworks/COMPLIANCE-EU.md (EAA, EU AI Act, GDPR) — absent from 100% of purely technical starter kits. The only kit that treats brand positioning as a professional standard.

---

Situational frameworks

Framework	Pull it when
BRAND-STRATEGY.md	Before any visual design — Golden Circle, archetypes, narrative
PROJECT-SCOPING.md	Before starting — Shape Up Pitch + Pre-mortem
ESTIMATION.md	Before any deadline commitment — PERT + ×1.5 rule
CLIENT-HANDOFF.md	Final delivery — access, docs, SLA
INCIDENT-RESPONSE.md	Service outage — blameless postmortem
ADR-TEMPLATE.md	New architectural decision
SLO-TEMPLATE.md	Define reliability objectives
COMPLIANCE-EU.md	Project delivered to European clients
DEPENDENCY-MANAGEMENT.md	Setup + monthly dependency maintenance
COMPETITIVE-AUDIT.md	Before any launch — Blue Ocean, Nielsen Heuristics, Mystery Shopper
CAMPAIGN-STRATEGY.md	Campaign launch — SEE-THINK-DO-CARE, funnel, KPIs
UX-RESEARCH.md	Before any feature — JTBD, interviews, usability testing (Nielsen, Fitzpatrick)
SOCIAL-CONTENT.md	Social presence launch — pillars, calendar, tone, creators

---

Integrated sources (excerpt)

Domain	Sources
Security	OWASP Top 10, NIST SP 800-63B, CWE Top 25
Performance	Google Core Web Vitals, DebugBear
Accessibility	WCAG 2.1 W3C, EN 301 549, Nielsen Norman Group
Design	Gestalt (1920), Bringhurst (1992), Baymard Institute
Testing	Martin Fowler pyramid, Agile Alliance DoD
Reliability	Google SRE Book, AWS Well-Architected
Resilience	Michael Nygard (Release It! 2018)
Green IT	ISO/IEC 21031:2024 (SCI)
Brand	Sinek (2009), Jung/Mark & Pearson (2001), Donald Miller (2017)
Estimation	PERT (1957), Kahneman & Tversky (Nobel 2002)
AI / LLM	Anthropic docs, Lakera, Nature 2025
Token Economy	Anthropic Pricing 2025, arXiv 2601.08815, Empirical (3.2x validated)
EU Legal	Regulation EU 2024/1689, EAA, ENISA NIS2

---

Full structure

project-kit/
├── .claude-plugin/         → Plugin manifest (auto-discovery for Claude Code)
│   └── plugin.json         → Registers agents, skills, hooks, commands
├── IDENTITY-TEMPLATE.md    → Identity sheet to personalise
├── METHODOLOGY.md          → Full method (read first)
├── DISCOVERY-GUIDE.md      → 10-Minute kit tour, PDF-ready
├── contracts/              → 40 contracts (thresholds + sources)
├── frameworks/             → 13 situational tools
├── audits/                 → 14 audits scoring /100
├── agents/                 → 14 agents (audit agents + Haiku research subagents)
├── skills/                 → 10 skills (/new-feature, /pre-deployment, /monthly-review, /compliance-check, /risk-score…)
├── commands/               → 4 slash commands (/init-project, /full-audit…)
├── hooks/                  → Plugin hooks
│   ├── hooks.json          → Declarative hook config (SessionStart, PreCompact, etc.)
│   └── scripts/            → 22 hook scripts (no-secrets, build-before-commit, session-context…)
├── workflows/              → 3 process templates (Observable Truths gates)
├── templates/              → CLAUDE.md, settings.json, github-actions/verify-kit.yml…
├── scripts/                → init-project.sh (--plugin flag), verify-kit.sh, verify-project.sh
├── global/                 → User-level layer for ~/.claude (v4)
│   ├── CLAUDE.md           → Global instructions template
│   ├── install-global.sh   → Installer (backup, merge, idempotent)
│   ├── hooks/              → 18 hooks + lib/ + tests/ + settings-hooks.json
│   ├── scripts/            → 17 ops scripts + lib/ + tests/
│   ├── skills/ commands/ agents/
│   └── settings.example.json
└── docs/                   → MEMORY-SYSTEM.md, SKILLS-GOVERNANCE.md

---

Contributing

See CONTRIBUTING.md.

Golden rule: every new rule = a Tier 1 source (official docs) or Tier 2 (academic/industrial). No opinions without a source. Numerical threshold required.

---

Want this level of quality without handling it yourself?

This kit is the public method of two sister studios. Each one applies it as a delivery baseline, in its own specialty.

	SQWR Studio	Flows Studio
Specialty	Branding and design	Automation and agentic development
What they build	Brand identities, design systems, websites and digital products with a strong visual signature	AI agents for businesses (support, concierge, email, social, SEO), workflow automation, custom agentic systems
Kit layer they live in	Design, accessibility, motion and brand contracts, design generation protocol	Agent and AI-safety contracts, the user-level global/ layer: hooks, memory, cost and governance
Typical engagements	Brand strategy, identity, web design and build, design audit /100	Agent design and deployment, automation audit, Claude Code setup and team training
Contact	studio@sqwr.be	contact@flows-studio.com

A score of 85/100 or more is not a goal. It is the delivery baseline of both studios.

---

Licence

MIT — free to use, modify, and distribute.

---