Development Guidelines for AI-Assisted Programming

Comprehensive CLAUDE.md guidelines + specialized agents for Test-Driven Development, TypeScript strict mode, and functional programming. Works with both Claude Code and OpenCode.

👆 Watch a real coding session showing how CLAUDE.md guides AI pair programming in Claude Code.

What This Is

This is my personal dotfiles repository. I use it to manage my shell configurations, git aliases, and development environment setup.

It became unexpectedly popular when I shared the CLAUDE.md file - development guidelines I wrote for AI-assisted programming. That's likely why you're here.

This repository now serves two purposes:

CLAUDE.md + Skills + Nine specialized agents + Three slash commands - Development guidelines, auto-discovered first-party skill patterns + 18 impeccable design skills from pbakaus/impeccable + 6 web quality skills from addyosmani/web-quality-skills + 3 Next.js skills from vercel-labs/next-skills + the optional grill-me planning interview skill from mattpocock/skills + the seo-audit marketing skill from coreyhaines31/marketingskills, and automated quality guidance (what most visitors want)
Personal dotfiles - My shell configs, git aliases, and tool configurations (what this repo was originally for)

Most people are here for CLAUDE.md and the agents. This README focuses primarily on those, with dotfiles coverage at the end.

Using another coding agent? Skills install via skills.sh, which supports 40+ coding agents (Claude Code, Cursor, Codex, Copilot, OpenCode, Gemini CLI, Cline, Continue, Windsurf, …). Pass --agent <name> (repeatable) to target others, or --with-opencode for the OpenCode config shortcut. Slash commands and Claude-Code agents are Claude-Code-specific; --with-opencode also copies them into OpenCode's equivalents. See Targeting other agents for details.

📘 CLAUDE.md: The Development Framework

→ Read the full CLAUDE.md file

CLAUDE.md is a living working-policy document for this repository. Canonical skills own reusable practices; source, tests, glossaries, accepted decisions, and maintained docs own the facts they can keep current.

Core Philosophy

TDD is non-negotiable for behavior change - New or changed behavior uses fast RED-GREEN-REFACTOR increments; mutation or alternate evidence is applied once at the end-of-phase PR-readiness gate
Behavior over implementation - Tests verify what code does, not how it does it
Immutability by default - Pure functions and immutable data structures
Schema-first with nuance - Runtime validation at trust boundaries, types for internal logic
Semantic refactoring - Abstract based on meaning, not structure
Reuse before invention, with evidence - Check local/platform capabilities and established solutions before owning material generic machinery; keep bespoke as a serious baseline
Explicit documentation - Capture learnings while context is fresh

What Makes It Different

Unlike typical style guides, CLAUDE.md provides:

Decision frameworks - Concrete questions to answer before taking action
Priority classifications - Objective severity levels (Critical/High/Nice/Skip)
Quality gates - Verifiable checklists before commits
Anti-pattern catalogs - Side-by-side good/bad examples
Git verification methods - How to audit compliance retrospectively

Key Sections

Section	What It Provides	Detailed Patterns
Testing Principles	Behavior-driven tests, isolated state, contextual fixtures, and repository-owned coverage diagnostics	→ skills/testing
Mutation Testing	End-of-phase Stryker full/diff runs, survivor triage, mutator-rule resource	→ skills/mutation-testing
Test Design Review	Evidence-based qualitative review against Dave Farley's eight properties, with unknowns left unscored	→ skills/test-design-reviewer
Front-End Testing	Claim-appropriate Browser Mode, Playwright, or DOM Testing Library patterns	→ skills/front-end-testing
React Testing	Browser Mode or React Testing Library selected by observable claim, repository support, and cost	→ skills/react-testing
TypeScript Guidelines	Schema-first decision framework, type vs interface clarity, immutability patterns	→ skills/typescript-strict
TDD Process	RED-GREEN-REFACTOR increments, end-of-phase mutation/alternate-evidence PR gate, quality gates, anti-patterns	→ skills/tdd
Refactoring	Priority classification, semantic vs structural framework, DRY decision tree	→ skills/refactoring
Reduce System Complexity	Behavior and guarantee conservation ledger, whole-mechanism accounting, first-principles minimum, and separate behavior/mechanism gates	→ skills/reduce-system-complexity
Codebase Design	Deep, cohesive modules; full caller-facing contract burden; information hiding; leverage and locality; justified seams; Design It Twice	→ skills/codebase-design
Improve Codebase Architecture	Evidence-led architecture audits that rank bounded candidates and produce self-contained visual HTML reports with before/after diagrams	→ skills/improve-codebase-architecture
Evaluate Existing Solutions	Local-first, current evidence for adopt/adapt/combine/build decisions across primitives, libraries, tools, applications, frameworks, and services	→ skills/evaluate-existing-solutions
Functional Programming	Immutability violations catalog, pure functions, composition patterns	→ skills/functional
Expectations	Routes reusable principles, local policy, vocabulary, decisions, behavior, and temporary delivery knowledge to the artifact that owns each truth	→ skills/expectations
Planning	Turn a selected child story into vertical implementation slices, or sequence a reducer-defined program, with a delivery shape for each slice	→ skills/planning
Story Splitting	Turn broad stories, epics, features, and backlog items into independently valuable child stories; based on Tim Ottinger's story-splitting resource list and linked articles	→ skills/story-splitting
Stack Pull Requests	Decide whether vertical implementation work should use independent PRs or an optional hard-/flow-lineage stack across one or more slices, then deliver it safely	→ skills/stack-pull-requests
Debugging	Evidence-preserving diagnosis for local and runtime failures: reproduce, localize, and test one falsifiable hypothesis; fix the owning boundary and leave a guard only when a fix was requested	→ skills/debugging
Graph Engineering	Compose installed skills into orchestrated multi-agent graphs — one sub-agent per skill, stages that fan out, adversarially verify, and synthesize	→ skills/graph-engineering
Panel Review	Multi-agent code review of any change boundary — working tree, branch, or PR — with installed skills as composable lenses (`/panel-review`), plus the PR-readiness evidence gate for creating PRs	→ skills/panel-review
CI Debugging	Systematic CI/CD failure diagnosis, hypothesis-first debugging, environment delta analysis	→ skills/ci-debugging
Production Parity Skill Builder	Creates app-specific skills that inspect docs, code, tests, CI, deployment, infrastructure, config, auth, and environment setup to catch drift between production and non-production environments	→ skills/production-parity-skill-builder
Structure Codebase	Selects the lightest honest source-tree shape: first-class frontend structures, visible hexagonal boundaries when earned, and feature-, context-, endpoint-, workflow-, framework-, or shallow forms elsewhere; package/import enforcement and safe migrations	→ skills/structure-codebase
Hexagonal Architecture	Ports and adapters, driving/driven asymmetry, CQRS-lite, composition roots, cross-cutting concerns, DI patterns, anti-patterns with code examples, full worked example, incremental adoption. 7 resources including source notes	→ skills/hexagonal-architecture
Domain-Driven Design	Ubiquitous language, value objects, entities, aggregates, domain events (Decider pattern), domain services, specifications, bounded contexts with ACL, error modeling, layer ownership, and focused sources. 7 deep-dive resources	→ skills/domain-driven-design
Event Sourcing	Events as the source of truth, current state as a left fold (the Decider); event stores with optimistic concurrency, projections and read models, event versioning (tolerant reader/upcasting), snapshots, sagas, GDPR crypto-shredding, and behaviour-driven testing of deciders. Leads with a when-to-use complexity ladder. 8 deep-dive resources + source notes	→ skills/event-sourcing
Twelve-Factor App	Deploy-time config via environment variables or platform-native injection, stateless processes, graceful shutdown, structured logging, backing services	→ skills/twelve-factor
Impeccable Design	Comprehensive frontend design vocabulary: distinctive interfaces, systematic typography, OKLCH color, anti-AI-slop methodology + 17 steering commands	→ impeccable
API Design	Contract-first, Hyrum's Law, RFC 9457 errors, idempotency, rate limiting, REST conventions, pagination, backward compatibility, OWASP API Security Top 10. 5 deep-dive resources + source notes	→ skills/api-design
Secure OAuth and OIDC	RFC 9700 / BCP 240 security workflow for OAuth 2.0 and OpenID Connect: applicability-aware controls, issuer and transaction binding, ID Token validation, attack catalog, negative tests, migrations, and evidence-based audits	→ skills/secure-oauth-oidc
BFF Design	The backend-for-frontend pattern itself: adoption signals and honest costs, one-experience-one-BFF granularity with frontend-team ownership, the shape-don't-decide rule, upstream aggregation with partial-failure and resilience budgets, identity-keyed caching, user-identity mediation toward upstreams (token exchange, confused-deputy prevention), and the alternatives (gateway, GraphQL federation, token-mediating backend, meta-framework server). 4 deep-dive references	→ skills/bff-design
BFF Entry Points	Explicit public/protected access classification for every BFF/backend HTTP entry point, a composition-prepared endpoint registrar that installs session/CSRF/Origin/Fetch Metadata policy by construction, provider-free in-application authorization, protected SSE/WebSocket registration, browser session coordination, and automated enforcement gates. 6 deep-dive references	→ skills/bff-entry-points
CLI Design	Unix-composable CLI patterns: stdout/stderr stream separation, format flags (--json/--plain), exit codes, TTY detection, composability, error design. Language-agnostic principles with TypeScript implementation patterns. 4 deep-dive resources	→ skills/cli-design
Finding Seams	Identifying substitution points in untestable code -- function parameter, configuration, module, and object seams for TypeScript/JS. FP-first with OOP patterns in a separate resource for legacy class-based code. Based on Michael Feathers' Working Effectively with Legacy Code. 3 deep-dive resources	→ skills/finding-seams
Characterisation Tests	Documenting actual behavior of existing code before making changes. The 5-step algorithm, heuristics, modern tooling (Vitest snapshots, combination testing, approval testing). Based on Michael Feathers' Working Effectively with Legacy Code. 2 deep-dive resources	→ skills/characterisation-tests
Storyboard	Optional working audit for a multi-surface UX when side-by-side mocks and flow gaps materially improve review; delete it after use unless the project maintains it	→ skills/storyboard
Teach Me	Evidence-based private tutor for any topic. Mission-grounded learning plans, discovery interview, trusted-source curation, Socratic questioning, Bloom's Taxonomy progression, spaced repetition, confidence calibration, learning records, living glossary, self-contained HTML lessons per session, course generation. 5 deep-dive resources. Invoked via `/teach-me [topic]`	→ skills/teach-me
Diagrams	Creates renderer-aware, evidence-backed, accessible diagrams with observable validation gates. The current core is an original rewrite; source notes preserve the removed historical import and published-history rights follow-up	→ skills/diagrams
Find Skills	Coordinates the minimum installed skill set first, then discovers installable skills through skills.sh or the reviewed `skills@1.5.22` CLI and inspects the full bundle, capabilities, provenance, license, maintenance, compatibility, and overlap. Vendored and locally hardened from vercel-labs/skills at `0b8fb22`; source notes distinguish the import-time MIT declaration from the later full upstream notice	→ skills/find-skills
Find Gaps	Conversational pre-implementation review for written stories, plans, acceptance criteria, specs, and design mocks. Surveys the artifact with a per-type checklist, then walks you through gaps one question at a time, turning each answer into an artifact-native precondition/trigger/outcome criterion, plan paragraph, or mock-state spec written back to the source of truth. Output is the tightened artifact, not a separate gap report. Pairs with `storyboard` for multi-mock audits	→ skills/find-gaps
Acceptance Review	Read-only criterion-by-criterion proof of whether a PR, branch, diff, or implementation satisfies its authoritative requirement	→ skills/acceptance-review
WTF	Explicitly re-explains the immediately previous model response in plain, precise UK English without starting new work. Invoke with `/wtf` in Claude Code or `$wtf` in Codex	→ skills/wtf
Grill Me (optional external)	One-question-at-a-time decision-tree interviews before story splitting, planning, or implementation; omitted by `--no-external`, with `specification` as the first-party fallback	→ skills.sh/mattpocock/skills/grill-me
Next.js Skills	Best practices for App Router, RSC boundaries, async APIs, metadata, Cache Components, and Next.js upgrades	→ next-skills
Web Quality Audit	Comprehensive Lighthouse-based quality review across all categories	→ web-quality-skills
Performance	Loading speed, runtime efficiency, resource optimization	→ web-quality-skills
Core Web Vitals	LCP, INP, CLS specific optimizations	→ web-quality-skills
Accessibility	WCAG compliance, screen reader support, keyboard navigation	→ web-quality-skills
SEO	Search engine optimization, crawlability, structured data	→ web-quality-skills
SEO Audit	Full SEO diagnosis across crawlability, indexation, on-page optimization, content quality, and action planning	→ marketingskills/seo-audit
Best Practices	Security, modern APIs, code quality patterns	→ web-quality-skills

📖 Skills Guide

v3.0 Architecture: Skills are auto-discovered patterns loaded on-demand when relevant. This reduces always-loaded context from ~3,000+ lines to ~160 lines.

Quick Navigation by Problem

"I'm struggling with..." → Go here:

Problem	Skill	Key Insight
Tests that break when I refactor	testing	Test behavior through public APIs, not implementation
100% coverage but bugs still slip through	mutation-testing	Coverage measures execution, mutation testing measures detection
Tests break when refactoring UI components	front-end-testing	Match the harness to the claim and query by role
Testing React components, hooks, or context	react-testing	Use Browser Mode for browser-observable behavior; keep a lighter stable harness when it proves the contract
Don't know when to use schemas vs types	typescript-strict	5-question decision framework
Code that "looks the same" - should I abstract it?	refactoring	Semantic vs structural abstraction guide
Refactoring everything vs nothing	refactoring	Priority classification (Critical/High/Nice/Skip)
Understanding what "DRY" really means	refactoring	DRY = knowledge, not code structure
A simplification may only be moving complexity elsewhere	reduce-system-complexity	Conserve agreed behavior, measure the complete path before/after, and require both behavior and mechanism gates
A module makes callers understand its implementation	codebase-design	Hide coherent decisions behind a smaller complete contract; optimize leverage and locality, not line count
Don't know where architecture work would pay off	improve-codebase-architecture	Rank evidence-backed candidates and compare them visually in an offline HTML report
About to build generic machinery that may already exist	evaluate-existing-solutions	Inspect local/platform primitives, research current established options, and compare them with a genuine bespoke baseline
Accidental shared-state mutation	functional	Ownership-aware immutable alternatives
Writing code before tests	tdd	RED-GREEN-REFACTOR with observable evidence, independent of commit choreography
Losing context on complex features	expectations	Learning capture framework (7 criteria)
Requirement is still fuzzy or decision-heavy	specification	Resolve one question at a time into examples and acceptance criteria; use optional `grill-me` when installed for extra pressure-testing
Turning a broad requirement into stories	story-splitting	Produce independently valuable child stories with scope, deferrals, and acceptance examples
Planning significant implementation work	planning	Sequence a selected child story vertically, or a reducer-defined program, and choose each slice's delivery shape
One slice is too large, or later slices should start before lower PRs merge	stack-pull-requests	Choose independent PRs or a justified hard-/flow-lineage stack without turning technical layers into stories
Need several skills applied to one task at once	graph-engineering	One orchestrator, one sub-agent per skill — fan out, adversarially verify, synthesize one deliverable
Want your work reviewed through your architecture skills — before or after opening a PR	review	`/panel-review [target] [lens skills...]` — working tree, branch, or PR; every lens is an installed skill; findings are verified into one ranked report
Tightening a story, plan, AC set, or mock	find-gaps	Find missing decisions and write confirmed answers back into the artifact
Checking whether implementation satisfies agreed requirements	acceptance-review	Map every authoritative criterion to implementation and verification evidence, then return an exact verdict
Backlog items keep turning into frontend/backend tickets	story-splitting	Reject component stories; split by capability, path, interface, data, rules, quality, or learning
A local or runtime failure needs a root cause	debugging	Preserve evidence, reproduce, localize, and test one causal hypothesis; implement only when a fix was requested
CI pipeline keeps failing	ci-debugging	Every failure is real until proven otherwise, hypothesis-first diagnosis
Local, CI, PR, or staging differs from production	production-parity-skill-builder	Generate an app-specific parity skill that inspects source, infra, config, and auth before asking targeted questions
Project folders hide ownership or architecture	structure-codebase	Select the lightest honest shape; make hexagonal inside/outside visible only when real and keep every interior featureful
Separating domain from infrastructure	hexagonal-architecture	Ports define contracts, adapters implement them, domain stays pure
Complex business rules need modeling	domain-driven-design	Ubiquitous language, glossary enforcement, value objects, aggregates
History and audit are part of the domain	event-sourcing	Events are the source of truth; current state is a left fold you can always rebuild
Deploy-varying config embedded in source or build artifacts	twelve-factor	Validate injected config at startup and pass it through composition options
Service won't scale horizontally	twelve-factor	Stateless processes, external backing services, graceful shutdown
UI looks generic or AI-generated	impeccable	`/impeccable teach` to set context, `/impeccable craft` to build with design methodology
Need to plan UX before coding	impeccable	`/shape` produces a design brief; `/impeccable craft` runs the full shape-build-iterate flow
Design needs professional polish	impeccable	`/critique` for UX review, `/polish` for final pass, `/harden` for production readiness
Typography or color needs work	impeccable	`/typeset` for font selection and hierarchy, `/colorize` for strategic OKLCH color
Designing REST APIs or consumer-facing contracts	api-design	Contract-first, Hyrum's Law, consistent error semantics, pagination
Breaking changes keep surprising consumers	api-design	Additive-only changes, One-Version Rule, input/output separation
Designing or auditing OAuth/OIDC login or delegated access	secure-oauth-oidc	Establish the security profile, then prove every issuer, transaction, code, token, and identity binding
Debugging token replay, mix-up, or multi-issuer login	secure-oauth-oidc	Trace the attack path and test hostile issuer, callback, redemption, and validation behavior
CLI output breaks when piped to jq	cli-design	stdout for data only, stderr for everything else
JSON mode includes spinners or progress	cli-design	Format flag contract, TTY detection, stream separation
Building a CLI that composes with Unix tools	cli-design	--json/--plain flags, exit codes, NDJSON streaming, stdin support
Code has dependencies I can't test around	finding-seams	Find substitution points (seams) without editing at the call site
Need to understand what code does before changing it	characterisation-tests	Let failing tests tell you what code actually does, not what it should do
Modifying code that has no tests	characterisation-tests	Pin down current behavior as a safety net, then refactor
Multiple UX mocks to review before code lands	storyboard	One HTML page with live iframes + flow diagram + gap cards; forces brainstorm questions per gap
Want "all the mocks in one place" for a feature	storyboard	Side-by-side embedded mocks + per-mock audit checklist, pairs with `/impeccable` pipeline
Want to learn a topic properly, not just read about it	teach-me	Socratic tutor, Bloom's progression, spaced repetition — invoked via `/teach-me [topic]`
Need a diagram, chart, or visualization in Markdown	diagrams	Decision guide picks Mermaid / Graphviz / Vega-Lite / PlantUML / Canvas / infographic for the job
Wishing an agent skill existed for this task	find-skills	Browse the open skills ecosystem first; verify the complete source before recommending or installing
Working on a Next.js App Router app	next-skills	Next.js best practices, Cache Components guidance, and official-upgrade workflow
Reviewing a plan, spec, or mocks before coding starts	find-gaps	Conversational loop: asks one question at a time and writes each answer back as a new AC / plan paragraph / mock-state spec
"What could go wrong?" / "What's missing?" on a design	find-gaps	Forces every gap category end-to-end; each confirmed answer updates the artifact, not a todo list
Want a plan interrogated before implementation	specification	Use its one-question protocol, or optional `grill-me` when installed, before implementation
Slow page loads or poor Lighthouse scores	performance	Critical rendering path, code splitting, image optimization
Failing Core Web Vitals (LCP, INP, CLS)	core-web-vitals	LCP < 2.5s, INP < 200ms, CLS < 0.1
Accessibility compliance gaps	accessibility	WCAG 2.1 guidelines, perceivable/operable/understandable/robust
Poor search engine visibility	seo	Technical SEO, structured data, meta tags, crawlability
Need to diagnose rankings, traffic drops, or SEO health	seo-audit	Prioritized audit across technical, on-page, content, and authority signals
Full site quality audit	web-quality-audit	Comprehensive Lighthouse audit across all categories

How Skills Work

Compatible agents auto-discover skills when relevant:

Writing TypeScript? → typescript-strict skill loads automatically
Running tests? → testing skill provides factory patterns
After GREEN? → refactoring skill assesses opportunities while behavior tests stay green
Ready to create a PR? → mutation-testing runs once for the accumulated change and drives survivor handling
Reviewing a PR, branch, or diff? → panel-review fans out one sub-agent per skill lens and synthesizes one adversarially verified, ranked report (/panel-review)
Task needs several skills at once? → graph-engineering composes installed skills into an orchestrated multi-agent graph, one skill per node
Removing whole-path mechanism without changing agreed behavior? → reduce-system-complexity keeps conservation and reduction as separate evidence gates
Designing one module's lasting responsibility and contract? → codebase-design applies deep-module, locality, and Design It Twice lenses
Looking for the highest-value architecture improvement? → improve-codebase-architecture creates an evidence-backed visual HTML report
Introducing a material generic mechanism or durable unresolved dependency? → evaluate-existing-solutions checks local/platform capabilities and current established options against bespoke
Reviewing test effectiveness? → mutation-testing skill identifies weak tests
Designing API endpoints? → api-design skill provides contract-first patterns
Building or reviewing OAuth/OIDC? → secure-oauth-oidc applies RFC 9700 plus the relevant identity and extension profiles
Splitting epics, large stories, or backlog items? → story-splitting preserves vertical user-value slices
One slice is hard to review, or later slices should start before lower PRs merge? → stack-pull-requests decides whether a hard-/flow-lineage stack earns its coordination cost
Investigating local/prod drift? → production-parity-skill-builder creates an app-specific parity skill from docs, source, tests, config, auth, and infra
Code with hard-to-test dependencies? → finding-seams skill identifies substitution points
Changing code with no tests? → characterisation-tests skill documents existing behavior
Building a UI? → impeccable skill loads design methodology and anti-slop patterns
Stress-testing a plan or design? → specification asks one focused question at a time; optional grill-me can deepen the interview when installed
Diagnosing a local or runtime failure? → debugging preserves evidence and tests one causal hypothesis at a time
Checking finished work against authoritative requirements? → acceptance-review returns a read-only criterion-by-criterion verdict
Need a second opinion on finished work? → double-check uses a read-only independent reviewer when available, or a disclosed fresh-context fallback, and re-reviews the final state until findings close
History and audit are part of the domain? → event-sourcing models current state as a left fold of immutable events (and tells you when not to)

Scope-to-Implementation Flow

For product work, the skills form a requirements-to-code pipeline. Each skill owns a different question and produces a different artifact:

Stage	Question	Skill	Output
1. Decide	Do we understand the product/design decision tree?	`specification`; optional `grill-me` when installed	Resolved decisions, acceptance examples, and remaining open questions
2. Split	What independently valuable child stories exist?	`story-splitting`	Child stories with value, scope, deferrals, acceptance examples, and release constraints
3. Tighten	What is missing, ambiguous, unverifiable, or unsafe?	`find-gaps`	Confirmed artifact updates: AC, plan paragraphs, mock-state specs, or a return to `story-splitting`
4. Select technology when needed	Should we reuse, adopt, adapt, combine, build, defer, or do nothing?	`evaluate-existing-solutions`	Current evidence, hard gates, qualitative trade-offs, ownership, and exit strategy
5. Plan	How do we implement the selected child story safely?	`planning`	Vertical slices in the repository's planning workflow (`plans/` fallback), with independent-PR or explicit dependency-stack delivery
6. Build	How do we change code without outrunning tests?	`tdd` + `testing` + applicable `refactoring`, then `mutation-testing` at PR readiness	RED-GREEN-REFACTOR for behavior change; verified preservation path for pure restructuring; one accumulated-scope mutation gate before PR
7. Accept	Does the final implementation satisfy the authoritative requirement?	`acceptance-review`	Read-only criterion evidence and an exact satisfies / does-not-satisfy / indeterminate verdict

Use the earliest stage that matches the uncertainty. Skip the decision interview when intent is already clear. Skip story-splitting for tiny or already-narrow work. Use find-gaps only once there is an artifact to inspect. Use technology selection proportionately for a material generic mechanism or durable new dependency—not domain logic, small glue, routine use of an already-adopted tool, or ordinary fixes. Use planning only after one child story or narrow capability and any consequential technology choice have been selected.

storyboard fits between Split and Tighten when UX spans multiple surfaces: it creates the visual artifact; find-gaps then reviews missing states and flow gaps.

No manual invocation needed - compatible agents detect when skills apply. Impeccable steering commands (/shape, /critique, /polish, etc.) can also be invoked directly. You can explicitly request the optional grill-me interview when it is installed.

🧪 Testing Principles → skills/testing

Problem it solves: Tests that break on every refactor, unclear what to test, low coverage despite many tests

What's inside:

Behavior-driven testing principles with anti-patterns
Fresh-state and contextual factory patterns for test data
Repository-owned coverage as a diagnostic, with behavior as the target
React component testing strategies
Reusing production schemas when they already own the contract

Concrete example from the docs:

// ❌ BAD - Implementation-focused test (breaks on refactor)
it("should call validateAmount", () => {
  const spy = jest.spyOn(validator, 'validateAmount');
  processPayment(payment);
  expect(spy).toHaveBeenCalled(); // Will break if we rename or restructure
});

// ✅ GOOD - Behavior-focused test (refactor-safe)
it("should reject payments with negative amounts", () => {
  const payment = getMockPayment({ amountMinorUnits: -100, currency: 'GBP' });
  const result = processPayment(payment);
  expect(result.success).toBe(false);
  expect(result.error.message).toBe("Invalid amount");
});

Why this matters: The first test will fail if you refactor validateAmount into a different structure. The second test only cares about behavior - refactor all you want, as long as negative amounts are rejected.

Key insight: A separate payment-validator.ts file may be fully exercised through payment-processor behavior tests. Mirror implementation files only when the file itself is the stable public unit under test.

🧬 Mutation Testing → skills/mutation-testing

Problem it solves: 100% code coverage but bugs still slip through; tests that don't actually verify behavior; weak assertions that pass regardless of code correctness

What's inside:

Stryker-first workflow for full-project, incremental, and focused mutation runs against the current review base
A single end-of-phase PR-readiness gate instead of mutation runs after every TDD increment
Setup guidance for projects that do not already have a mutation testing harness
Survivor triage: fix obvious gaps immediately, ask for human judgment on subtle domain questions
On-demand mutator-rule resource with operator reference and weak vs strong test examples
Equivalent mutant identification, CI guidance, and TDD-based test strengthening patterns

The core insight:

Code coverage tells you what code your tests execute. Mutation testing tells you whether the tests would detect meaningful changes to that code. Complete line coverage alone does not prove that assertions protect behavior.

Concrete example from the docs:

// Production code
const calculateArea = (width: number, height: number): number => {
  return width * height;
};

// Mutant: width / height
// Question: Would tests fail if * became /?

// ❌ WEAK TEST - Would NOT catch mutant
it('calculates area', () => {
  expect(calculateArea(10, 1)).toBe(10); // 10 * 1 = 10, 10 / 1 = 10 (SAME!)
});

// ✅ STRONG TEST - Would catch mutant
it('calculates area', () => {
  expect(calculateArea(10, 3)).toBe(30); // 10 * 3 = 30, 10 / 3 = 3.33 (DIFFERENT!)
});

Why this matters: The first test uses an identity value (1) that produces the same result for both multiplication and division. The second test uses values that would produce different results, catching the bug.

Key insight: Avoid identity values (0 for +/-, 1 for */, empty arrays, all true/false for logical ops) in tests - they let mutants survive.

🔷 TypeScript Guidelines → skills/typescript-strict

Problem it solves: Overusing schemas everywhere, or not using them when needed; confusion about type vs interface

What's inside:

Strict mode requirements and tsconfig setup
Type vs interface semantics with repository convention first
Boundary decision framework: When runtime schemas are required
Schema-first development with Zod
Schema usage in tests (import from shared locations, never redefine)
Branded types for type safety

The boundary framework from the docs:

Ask these in order:

Does untrusted data cross a runtime boundary? → ✅ Validate with a schema
Is the contract exchanged between independently deployed systems? → ✅ Validate at ingress/egress
Does a production schema already exist for a contract-shaped fixture? → Reuse it when that adds evidence
Is this a trusted internal invariant? → A type, smart constructor, or domain value may be clearer

Concrete example from the docs:

// ❌ Schema NOT needed - pure internal type
type Point = { readonly x: number; readonly y: number };
type SearchWindow = { readonly offset: number; readonly limit: number };

// ✅ Schema REQUIRED - API response (trust boundary + validation)
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "guest"]),
});
const user = UserSchema.parse(apiResponse);

Key insight: Not all types need schemas. Use schemas at trust boundaries and for validation. For internal types and utilities, plain TypeScript types are sufficient.

Critical rule: When a production schema exists and is relevant to the test's claim, import it rather than redefining the same contract. Do not invent a runtime schema solely for a test factory.

🔄 Development Workflow (TDD + Refactoring) → skills/tdd + skills/refactoring

Problem it solves: Writing code before tests, refactoring too much/too little, not knowing when to abstract

What's inside:

TDD process with quality gates (what to verify before each commit)
RED-GREEN-REFACTOR increments followed by one mutation or reviewed alternate-evidence gate when the phase is ready for a PR
Refactoring priority classification (Critical/High/Nice/Skip)
Semantic vs structural abstraction (the most important refactoring rule)
Understanding DRY - knowledge vs code duplication
4-question decision framework for abstraction
Git verification methods (audit TDD compliance retrospectively)
Commit guidelines and PR standards

The refactoring priority system from the docs:

🔴 Critical (Fix Now): Behavior-changing mutation, divergent copies of one business rule, control flow that obscures a high-risk path

⚠️ High Value (Fix This Session): Unclear names, magic numbers, functions coordinating multiple responsibilities

💡 Nice to Have: Minor improvements

✅ Skip: Code that's already clean, structural similarity without semantic relationship

The semantic vs structural rule (THE BIG ONE):

// ❌ DO NOT ABSTRACT - Structural similarity, DIFFERENT semantics
const validateUploadBytes = (bytes: number): boolean => {
  return Number.isSafeInteger(bytes) && bytes > 0 && bytes <= 10_000_000; // Storage rules
};

const validateBatchSize = (items: number): boolean => {
  return Number.isSafeInteger(items) && items > 0 && items <= 10_000; // Worker rules
};
// They'll evolve independently - abstracting couples unrelated business rules

// ✅ SAFE TO ABSTRACT - Same semantic meaning
const formatUserDisplayName = (first: string, last: string) => `${first} ${last}`.trim();
const formatCustomerDisplayName = (first: string, last: string) => `${first} ${last}`.trim();
const formatEmployeeDisplayName = (first: string, last: string) => `${first} ${last}`.trim();
// All represent "how we display person names" - same business concept

const formatPersonDisplayName = (first: string, last: string) => `${first} ${last}`.trim();

Key insight: "Duplicate code is far cheaper than the wrong abstraction." Only abstract code that shares the same semantic meaning, not just similar structure.

DRY revelation: DRY means "Don't Repeat Knowledge" not "Don't Repeat Code Structure". The shipping threshold example in the docs shows this perfectly.

🎨 Code Style (Functional Programming) → skills/functional

Problem it solves: Accidental mutations, nested conditionals, unclear code, when to use FP abstractions

What's inside:

Immutable alternatives for shared values and declared immutable contracts
Functional programming patterns and when to use heavy FP abstractions
Contextual control-flow guidance without a fixed nesting limit
Self-documenting code plus comments for non-obvious reasoning, constraints, and trade-offs
Naming conventions (functions, types, constants, files)
Options objects pattern when parameter meaning or evolution makes positional calls unclear

The immutability catalog from the docs:

// Avoid when callers share or rely on the original array
items.push(newItem);        // → [...items, newItem]
items.pop();                // → items.slice(0, -1)
items[0] = updatedItem;     // → items.map((item, i) => i === 0 ? updatedItem : item)
items.sort();               // → [...items].sort()

// Avoid when the object crosses an ownership boundary
user.name = "New Name";     // → { ...user, name: "New Name" }
delete user.email;          // → const { email, ...rest } = user; rest

// Avoid when the nested value is part of an immutable contract
cart.items[0].quantity = 5; // → { ...cart, items: cart.items.map((item, i) => i === 0 ? { ...item, quantity: 5 } : item) }

Options objects pattern:

// Avoid: Unclear at call site
const payment = createPayment(10_000, "GBP", "card_123", "cust_456", undefined, { orderId: "789" });

// Good: Self-documenting
const payment = createPayment({
  amountMinorUnits: 10_000,
  currency: "GBP",
  cardId: "card_123",
  customerId: "cust_456",
  metadata: { orderId: "789" },
});

Key insight: Prefer immutability at shared boundaries and for declared immutable values. Local mutation is acceptable when ownership is clear, the API contains it, or measurement shows it is the simpler safe implementation.

🤝 Working with Claude → skills/expectations

Problem it solves: Losing context after complex features, forgetting gotchas, unclear expectations

What's inside:

Complete expectations checklist for Claude
Learning documentation framework (7 criteria for what to document)
Types of learnings to capture (gotchas, patterns, anti-patterns, decisions, edge cases)
Documentation format templates
"What do I wish I'd known at the start?" prompts

The 7 criteria for documenting learnings:

Document if ANY of these are true:

✅ Would save future developers >30 minutes
✅ Prevents a class of bugs or errors
✅ Reveals non-obvious behavior or constraints
✅ Captures architectural rationale or trade-offs
✅ Documents domain-specific knowledge
✅ Identifies effective patterns or anti-patterns
✅ Clarifies tool setup or configuration gotchas

Documentation template from the docs:

#### Gotcha: [Descriptive Title]

**Context**: When this occurs
**Issue**: What goes wrong
**Solution**: How to handle it

```typescript
// ✅ CORRECT
const example = "correct approach";

// ❌ WRONG
const wrong = "incorrect approach";


**Key insight:** Capture learnings while context is fresh, not during retrospectives when details are lost. Ask "What do I wish I'd known at the start?" after every significant change.

---

### 🧱 Codebase Design → [skills/codebase-design](claude/.claude/skills/codebase-design/SKILL.md)

**Problem it solves:** Modules whose contracts expose their implementation, repeated caller orchestration, shallow pass-through layers, and consequential interface choices made from only one design

**What's inside (main skill + 3 references):**

- **Deep modules without god modules** — hide coherent policy, sequencing, representation, and recovery while respecting ownership, runtime, trust, and failure boundaries
- **Full interface burden** — operations, types, invariants, lifecycle, effects, errors, configuration, ordering, and relevant performance expectations
- **Leverage and locality** — make callers coordinate less and concentrate related knowledge, changes, bugs, and verification in one owner
- **Behavior-preserving inlining test** — distinguish a useful module from a pass-through without pretending its behavior can simply disappear
- **Evidence-justified seams** — retain Michael Feathers' enabling-point definition; do not equate every interface with a seam or port
- **Design It Twice** — compare genuinely different contracts for expensive-to-reverse decisions
- **Safe deepening** — characterize behavior, strengthen mutation detection, redirect callers incrementally, and replace tests only after equivalent behavior has credible preservation evidence

```text
small, stable caller burden
            │
            ▼
  cohesive module contract
            │ hides
            ▼
policy · sequencing · representation · recovery · provider mechanics

Depth is coherent capability per unit of caller burden, not lines of code. A deep public module may compose many small private pure functions.

🔭 Improve Codebase Architecture → skills/improve-codebase-architecture

Problem it solves: Architecture reviews that become generic cleanup lists, over-index on file size, consolidate thin adapters, or recommend speculative redesigns without showing why the work matters now

What's inside (main skill + 2 references):

Evidence-led target selection — change pressure, co-change, defects, caller burden, tests, ownership, runtime shape, and planned work
Balanced candidate generation — deepen, collapse pass-through chains, split incoherence, move seams, repair dependency direction, restore locality, or make effects and failures honest
Counterevidence and confidence — every candidate includes the strongest reason not to proceed and separates recommendation strength from certainty
First-class visual report — timestamped, self-contained, offline HTML with inline CSS and static SVG, before/after diagrams, candidate cards, evidence, risks, and one top recommendation
Safe selection boundary — audit first, then route a selected candidate to codebase-design, structure-codebase, and the appropriate test/refactoring skills

The architecture skills deliberately own different questions:

Question	Owning skill
Where would architecture investment pay off now?	`improve-codebase-architecture`
What coherent responsibility and caller-facing contract should the selected module own?	`codebase-design`
Where should that code live, and how should imports/packages enforce the boundary?	`structure-codebase`
How do we conserve agreed behavior while gathering same-scope evidence that total mechanism was removed rather than relocated?	`reduce-system-complexity`
Which existing capability or bespoke approach best satisfies a selected material generic need?	`evaluate-existing-solutions`

This keeps candidate discovery, logical module depth, physical topology, mechanism reduction, and technology choice separate while providing deliberate handoffs between them.

➖ Reduce System Complexity → skills/reduce-system-complexity

Problem it solves: “Simplifications” that shorten one file while exporting branches, state, dependencies, coordination, failure handling, or operational work to another owner

What's inside (main skill + evidence template + source notes):

Classified conservation contract — distinguishes documented contracts, downstream reliance, intended behavior, disputed bugs, and obsolete internals instead of preserving everything blindly
Whole-mechanism ledger — traces control, state/time, structure, variability, and operations across the complete trigger-to-outcome-and-recovery path
First-principles minimum — retains only mechanism earned by domain outcomes, external constraints, ownership, time, failure, and recovery
Qualitative slice selection — complete mechanism removed first, preservation confidence second, blast radius/recovery as tie-breakers; no false-precision formula
First-class migration states — a transition passes the behavior gate and independent checks while its mechanism gate stays pending with no net claim; any bridge has bounded owner/removal metadata, and only the linked terminal slice may pass both gates and claim retired mechanism
Separate behavior and mechanism gates — tests and provider evidence show conservation confidence; same-scope before/after observations show whether ownership actually fell
Correct TDD relationship — pure reductions use the REFACTOR path from passing proportionate preservation evidence; changed behavior returns to RED

The skill is an attributed adaptation of Adam Bulmer's reducer, renamed to avoid Redux/functional-reducer ambiguity and narrowed so it does not collide with architecture discovery or ordinary cleanup.

🔎 Evaluate Existing Solutions → skills/evaluate-existing-solutions

Problem it solves: AI or human designs that reinvent generic machinery without checking established options—or add a popular dependency without accounting for its real lifecycle cost

What's inside (main skill + 2 evidence references + reusable decision template):

Proportionate always-on gate — lightweight local/platform preflight before bespoke generic machinery, due diligence for a named new material dependency, and full comparison only for unresolved consequential choices
Local-first search order — existing repository capabilities, standards, standard library, framework/runtime/platform primitives, and already-supported dependencies before external shopping
Current primary evidence — exact version/tier, release/support state, security, license, compatibility, pricing, data handling, and evidence date; popularity is only a discovery signal
Real candidate set — do nothing/local reuse, primitive, library, OSS application/tool, managed service, adapt/combine, and a genuine bespoke baseline
Hard gates before trade-offs — functional, architecture, security/privacy, license/procurement, reliability, operations, performance, testability, total ownership, team fit, and exit strategy without weighted-score theatre
Safe proof of fit — isolated, authorized spikes answer a named uncertainty without installing untrusted code, creating accounts, or exposing data by default
Explicit outcome and ownership — adopt, adapt, combine, build, defer, or do nothing, including remaining bespoke glue, upgrade/security owner, exit path, and re-evaluation triggers

Existing software is preferred when it reduces whole-lifecycle ownership and risk. Bespoke wins when the evidence shows better fit, control, security, reliability, performance, differentiation, or lower total mechanism.

🧭 Structure Codebase → skills/structure-codebase

Problem it solves: Frontend and backend source trees that either hide product behavior behind technical layers or apply the same architecture template to every project

What's inside (main skill + 5 references):

Architecture selection before folder generation — frontend route/feature, shallow, DDD-context, visible hexagonal, endpoint-first BFF, framework-host, and workflow-first operational forms
Visible hexagonal boundaries — hexagon/ as the complete provider-free inside, with driving/driven adapters and test interactors outside
Featureful interiors — domain concepts and use cases below the boundary instead of flat god files
BFF specialization — URL-first endpoints, explicit routers, sibling workflows, raw upgrade handling, and one-way development routing
Composition roots — explicit concrete wiring in nontrivial executable hosts without ceremonial folders in libraries or small apps
Mechanical truth — package manifests, public exports, recursive discovery, role-based imports, architecture tests, and target-depth fixtures
Safe migration — separate characterization, dependency inversion, behavioral decomposition, and physical reparenting
Proportionate fallbacks — ordinary CRUD services, framework-constrained backends, ops tools, and small libraries avoid DDD/hexagonal cargo culting
Frontend architecture — first-class route-colocated, feature-first, meta-framework, design-system, state/data ownership, runtime-boundary, and monorepo guidance

The core insight:

product or capability
  ├── hexagon/             # inside, only when ports-and-adapters is real
  │   └── feature/use-case
  ├── adapters/            # concrete outside technology
  └── testing/             # outside test interactors

Product meaning belongs at the capability root, architectural vocabulary belongs at real seams, and behavior that changes together stays close inside each zone. Folder names make claims; packages and import rules prove them.

folder-structure remains temporarily as a deprecated explicit-invocation redirect for installed users; all new guidance and documentation use structure-codebase.

🏗️ Hexagonal Architecture → skills/hexagonal-architecture

Problem it solves: Business logic tangled with database queries and HTTP handlers; untestable code; changing a database requires rewriting business rules

What's inside (main skill + 7 resources):

Driving/driven adapter asymmetry with visual diagram — HTTP routes, queue consumers, cron jobs
Dependency injection via parameters — wrong/right comparison, composition root pattern
CQRS-lite — reads bypass repositories, query functions JOIN freely
Cross-cutting concerns — where auth, logging, transactions, and error formatting live
Anti-patterns with code — business logic in adapters, bypass adapters, technology-shaped ports
Full worked example — one feature traced through every layer with tests and file map
Incremental adoption — strangler fig approach for existing codebases
Authoritative sources — Cockburn, Seemann, Pierrain, Graca, Netflix, Valentina Jemuović

The core insight:

// ❌ Business logic tangled with infrastructure
export async function POST(request: Request) {
  const order = await db.select().from(orders).where(eq(orders.id, id)).get();
  if (order.itemCount > 100) await requireManagerApproval(order); // business rule in route handler!
  ...
}

// ✅ Domain stays pure; adapters are thin glue
const placeOrder = (order: Order): PlaceOrderResult => {
  if (order.itemCount > 100) return { success: false, reason: 'requires-approval' };
  ...
};

Key insight: If swapping your database requires changing business logic, the boundary is wrong. The worked example shows the full picture from glossary through domain through adapters to tests.

📐 Domain-Driven Design → skills/domain-driven-design

Problem it solves: Business rules scattered across route handlers and database queries; technical jargon instead of domain language; models that don't evolve as understanding deepens

What's inside (main skill + 7 deep-dive resources):

"Where Does This Code Belong?" — decision framework for the most common DDD question
Building blocks — value objects, entities, aggregates, domain events (Decider pattern), domain services, specifications, branded types with factory functions
Make Illegal States Unrepresentable — boolean-to-union pattern + exhaustive switch
Error modeling — result types for business outcomes, exceptions for bugs
Bounded contexts — ACL, context mapping, comprehensive discovery methodology
Event dispatch — in-process, outbox pattern, process managers
Model evolution — domain models should evolve; the first model is never the final model
Authoritative sources — Evans, Vernon, Wlaschin, Chassaing, Khorikov, Valentina Jemuović

The decision framework from the docs:

Question	If yes →
Does it enforce a business rule?	Domain policy; physical location follows the selected project structure
Does it orchestrate without owning the rule?	Application policy / use case
Does it format data for display?	Presentation code — purity is not sufficient
Does it talk to an external system?	Integration/infrastructure code; a driven adapter only in a hexagonal system
Is it framework glue?	Framework entrypoint; a driving adapter only in a hexagonal system

Key insight: Domain models evolve as understanding deepens — this is expected and ideal, not a sign of failure. TDD makes this evolution safe: rename a concept, update the glossary, and the tests guide the migration.

📜 Event Sourcing → skills/event-sourcing

Problem it solves: The domain's history is a first-class requirement — audit, temporal queries, replay, multiple read models over the same facts — and current-state storage throws that history away

What's inside (main skill + 8 deep-dive resources + source notes):

When to use it (and when not) — the complexity ladder (explicit returns → domain events → outbox → event sourcing); event sourcing vs CQRS vs event-driven vs streaming vs CDC/audit log
The Decider write model — decide/evolve/initialState reused from the DDD skill; current state as a left fold of events; the load → rehydrate → decide → append command-handler loop
The event store as a driven port — a minimal interface, a concrete Postgres schema where atomic stream-head compare-and-swap enforces expected-version equality and UNIQUE (stream_id, version) is defense in depth, the event envelope with correlation/causation ids, and the TS/Node tooling landscape (Emmett, KurrentDB, message-db)
Events as data — past-tense business naming, EventStorming discovery, granularity (thin/fat/summary), internal vs external events, schema-first tolerant reader on read
Projections & read models — inline vs async, catch-up subscriptions and checkpoints, idempotency, eventual consistency and read-your-writes, rebuild-from-zero
Event versioning — the hardest part: immutability, weak schema, upcasting, copy-transform, and preventing the need to version at all
Production concerns — snapshots as a rebuildable cache, sagas for cross-aggregate work, delivery guarantees, compensating events, and GDPR crypto-shredding
Behaviour-driven testing — deciders, projections, and upcasters tested through the public API on observable output; the event-sourcing literature's "given-when-then" translated into this repo's testing style, no DSL

The core insight:

// State is never stored — it is a left fold of the events:
const rehydrate = (events: readonly AccountEvent[]): AccountState =>
  events.reduce(evolve, initialState);

// The write path: load → rehydrate → decide → append (with optimistic concurrency)
const decision = decide(command, rehydrate(events));
if (decision.accepted) await store.appendToStream(streamId, decision.events, { expectedVersion });

Key insight: Event sourcing persists the Decider you already have — decide produces events, evolve folds them back into state. It is the top rung of the complexity ladder: adopt it for the one or two bounded contexts whose history is part of the domain, never as a default.

🔌 API and Interface Design → skills/api-design

Problem it solves: Inconsistent API contracts, breaking changes that surprise consumers, endpoints returning different shapes, no pagination on list endpoints, duplicate operations from retried requests

What's inside (main skill + 5 deep-dive resources + source notes):

Hyrum's Law — every observable behavior becomes a de facto contract; design implications for what you expose
Contract-first development — define the interface before implementing (aligns with TDD: define what you want → test → implement)
RFC 9457 error semantics — standard application/problem+json format with security considerations, extension members, validation error patterns
Idempotency — HTTP method safety table, idempotency keys for POST (Stripe's pattern), making DELETE idempotent
Rate limiting — IETF draft structured fields (RateLimit / RateLimit-Policy), legacy header triplets, Retry-After, 429 responses
REST conventions — resource naming, PATCH vs PUT, pagination, filtering, sub-resources
Backward compatibility — additive-only changes, what breaks vs preserves contracts
Input/output separation — distinguish caller-provided data from server-generated fields
Common rationalizations table — "We'll document later", "We don't need pagination yet", "Retries are the client's problem"
Red flags and verification checklist
resources/api-evolution.md — Versioning strategies (Stripe's date-pinning, URL, header), Postel's Law, Sunset/Deprecation headers, enum evolution, consumer-driven contract testing (Pact)
resources/api-security.md — OWASP API Security Top 10 with TypeScript code examples, authentication patterns (API keys, OAuth2+PKCE, JWT tradeoffs), security checklist
resources/auth-security.md — JWT best practices (RFC 8725): algorithm allowlisting, claim validation, explicit typing, untrusted header inputs, and routing to the specialist OAuth/OIDC skill
resources/http-fundamentals.md — Building on HTTP semantics (RFC 9205): status code discipline, caching, URI schemes, browser security headers
resources/problem-details.md — RFC 9457 deep detail: ProblemDetail type, type-URI semantics, extension members, security considerations
resources/source-notes.md and LICENSE — immutable provenance audit baseline, explicit original-import history gap, local departures, and the applicable upstream MIT notice

Adapted from Addy Osmani's MIT-licensed api-and-interface-design skill. Local commit 05483d71b5d93ce1acc0287e07320b21a6d120b3 records the adaptation but not the upstream revision originally imported; 7676817c12a1317454ae3898a0c5c1eacf5dd3d5 is a pinned audit baseline, not an import-revision claim. The local skill is significantly expanded with RFC 9457, idempotency, rate limiting, OWASP API Security Top 10, versioning strategies, and deprecation patterns, and aligns TypeScript examples with local conventions. See the linked source notes and MIT notice for the complete record.

🔐 Secure OAuth and OpenID Connect → skills/secure-oauth-oidc

Problem it solves: OAuth and OIDC systems that pass a happy-path login test while leaving issuer mix-up, code injection, redirect, replay, token-substitution, or identity-binding weaknesses undiscovered

What's inside (main skill + 5 focused references):

Security-profile first — identifies goals, parties, real client confidentiality, every enabled flow, issuer/resource topology, applicable profiles, and inspected evidence before choosing controls
Transaction ledger — follows state, PKCE, nonce, authorization responses and codes, access and refresh tokens, and ID Tokens across creation, binding, validation, expiry, replay, and revocation
RFC 9700 control catalog — preserves BCP 14 strength, conditions, role, and source section instead of flattening every requirement into a generic checklist
OIDC validation — trusted issuer selection, Discovery and key binding, atomic ID Token validation, (iss, sub) identity, UserInfo subject equality, multi-issuer callbacks, hybrid/JARM distinctions, and logout boundaries
Complete threat catalog — maps RFC 9700's attacks to prerequisites, broken invariants, controls, and safe negative tests
Standards map — routes to PKCE, native apps, metadata, resource indicators, mTLS, DPoP, JWT access tokens, PAR/JAR/JARM, issuer identification, rich authorization requests, OIDC, and stricter FAPI profiles without treating drafts as final standards
Evidence-based review contract — distinguishes normative non-compliance, exploitable weakness, defense-in-depth, and unknowns; requires attack scenarios, precise evidence, remediation, and verification

Primary baseline: RFC 9700 / BCP 240 with the applicable OAuth extension and OpenID Connect specifications layered on top.

📕 Working with Legacy Code → skills/finding-seams + skills/characterisation-tests

These two skills are adapted from Michael Feathers' Working Effectively with Legacy Code (2004), one of the most influential books on software testing and design. Feathers provides a specific, deliberate definition of legacy code:

Legacy code is code without tests.

Code without tests is bad code. It doesn't matter how well written it is; it doesn't matter how pretty or object-oriented or well-encapsulated it is. With tests, we can change the behavior of our code quickly and verifiably. Without them, we really don't know if our code is getting better or worse.

-- Michael Feathers, Working Effectively with Legacy Code (2004)

This definition matters because it reframes the problem. Legacy code isn't about age, technology, or quality -- it's about the absence of a safety net. Code written yesterday without tests is legacy code. A twenty-year-old system with comprehensive tests is not.

The legacy code dilemma: You need tests to change code safely, but the code wasn't written for testability, so you can't easily write tests. Feathers' two key techniques break this catch-22:

Finding seams -- identify places where you can alter behavior without editing at that place, giving you substitution points to isolate code for testing
Characterisation tests -- write tests that document what the code actually does (not what it should do), creating a safety net for refactoring

These two skills bridge the gap between untested code and the TDD workflow that the rest of this framework assumes. Once you have seams and characterisation tests in place, the standard cycle takes over: refactor with confidence, then replace characterisation tests with proper behavior-driven tests over time.

How they fit the existing workflow:

Untested code
    ↓
finding-seams         → Break dependencies to make code testable
    ↓
characterisation-tests → Document actual behavior as a safety net
    ↓
tdd / testing          → Write proper behavior-driven tests for new changes
    ↓
refactoring            → Improve structure while behavior tests stay green
    ↓
mutation-testing       → At PR readiness, verify the accumulated change once

🔍 Finding Seams → skills/finding-seams

Problem it solves: Code has dependencies you can't test around -- direct construction of collaborators, static/global calls, tight coupling to databases or external services, singleton access patterns

What's inside (main skill + 3 deep-dive resources):

Core concept -- Feathers' definition: "A seam is a place where you can alter behavior in your program without editing in that place." Every seam has an enabling point.
4 seam types for TypeScript/JS -- function parameter seams (primary), configuration seams, module seams (vi.mock() -- last resort), object seams (legacy OOP only)
How to find seams -- 6 things to look for in existing code (function parameters, default values, imports, config, React props/context, hard-coded new)
The progression -- FP-first ordering (parameter injection → higher-order functions → configuration injection → module mocking → subclass override)
FP-first creation techniques -- parameterize function, higher-order factory, extract type, wrap calls, module indirection
OOP patterns in separate resource -- for legacy class-based code: object seams, extract and override, parameterize constructor
React/Next.js seams -- props as seams, context as seams, MSW as API boundary seam
Connection to hexagonal architecture -- ports are designed-in seams

Concrete example from the docs:

// BEFORE -- direct dependency, no seam
const scheduleDelivery = (delivery: Delivery): DeliveryPlan => {
  const transitDays = fetchTransitDays(delivery.region);  // calls external service
  return { ...delivery, totalDays: delivery.preparationDays + transitDays };
};

// AFTER -- function parameter seam (enabling point: the argument list)
type TransitDaysResolver = (region: string) => number;

const scheduleDelivery = (
  delivery: Delivery,
  resolveTransitDays: TransitDaysResolver = fetchTransitDays,  // default = production behavior
): DeliveryPlan => {
  const transitDays = resolveTransitDays(delivery.region);
  return { ...delivery, totalDays: delivery.preparationDays + transitDays };
};

// Test -- pass a fake at the seam
const delivery = { ...testDelivery, preparationDays: 3 };
const result = scheduleDelivery(delivery, () => 2);
expect(result.totalDays).toBe(5);

Key insight: In functional TypeScript, functions-as-values provide natural built-in seams everywhere. Every function parameter that accepts a callable is both a seam and its own enabling point -- no mocking framework required.

📋 Characterisation Tests → skills/characterisation-tests

Problem it solves: Modifying code with no tests and no specifications; needing to understand what code does before changing it; facing the legacy code dilemma where you need tests to refactor safely

What's inside (main skill + 2 deep-dive resources):

Core concept -- "A characterisation test characterizes the actual behavior of a piece of code. There's no 'it should do this' -- the tests document what the system really does."
The 5-step algorithm -- use code in test harness, write assertion you know will fail, let failure tell you the behavior, change test to expect actual behavior, repeat
Feathers' heuristics -- use coverage as a guide; treat deployed behavior as compatibility evidence, not correctness authority; focus on the change area and mark suspicious behavior
When to stop -- cover every branch your change touches + one layer out; validate the accumulated change later at the end-of-phase mutation gate
Bug handling -- if system is deployed, someone may depend on the "bug"; document it, mark as suspicious, escalate
Preservation-strength validation -- use mutator rules cheaply while characterising, then run mutation testing once at PR readiness where meaningful; otherwise record explicit N/A plus proportionate alternate evidence
Sensing via parameter injection -- prefer function parameters over monkey-patching for observing code behavior
Modern tooling -- Vitest inline snapshots (toMatchInlineSnapshot()), combination testing, approval testing, coverage-guided characterisation

Concrete example from the docs:

// Step 1: Write an assertion you know will fail
it('characterises formatPrice', () => {
  expect(formatPrice(1999)).toBe('PLACEHOLDER');
});
// Test output: expected 'PLACEHOLDER' but received '$19.99'

// Step 2: Change test to expect actual behavior
it('characterises formatPrice', () => {
  expect(formatPrice(1999)).toBe('$19.99');
});

Key insight: Characterisation tests have no moral authority -- they don't assert correctness, they detect change. They are temporary scaffolding: once you understand the code and have proper behavior-driven tests, the characterisation tests can be retired. Like "walking into a forest and drawing a line -- after you own that area, you can develop it."

🕸️ Graph Engineering → skills/graph-engineering

Problem it solves: Tasks that need several installed skills applied at once — multi-lens reviews, multi-angle audits, migration sweeps — collapsing into one overloaded context where every lens goes blunt

What's inside (main skill + 3 references):

Skills-as-nodes — one orchestrator designs an agent graph (Claude Code's "dynamic workflows"); each node is a sub-agent that loads exactly one skill and works a bounded slice through only that lens
Design protocol — fix the deliverable, scout inline first, choose 3–6 relevant nodes, pick a topology, define structured output contracts
Topology catalog (topologies.md) — fan-out/fan-in, pipeline, adversarial verify, dedup barrier, judge panel, loop-until-dry
Node design (node-design.md) — node brief template, skill-resolution rules, evidence bar, severity taxonomy
Runtime ladder (execution.md) — Workflow tool, Agent-tool fan-out, or labelled sequential degraded mode
Honest scope — explicit anti-triggers: no graphs of one node, no fan-outs the user didn't opt into

panel-review is the flagship instance of this skill; double-check remains the tool for a single independent second opinion.

🔍 Panel Review → skills/panel-review

Problem it solves: code reviews that hardcode one generic checklist instead of composing the architecture skills your project actually uses, that can only run once a PR exists, and readiness evidence checked nowhere in particular

What's inside (main skill + 3 references):

Skills as review lenses — /panel-review [target] [lens skills...] reviews any boundary at any phase: uncommitted work (wip), the current branch, a stacked layer, or a PR (#123); every lens is an installed skill (hexagonal-architecture, domain-driven-design, structure-codebase, ...), each running as its own sub-agent with an isolated context
Composable roster (lenses.md) — defaults (typescript-strict, functional, testing + built-in readiness and quality lenses) plus project-trait auto-detection; add or remove lenses, only, thorough, and post tokens
PR-readiness evidence gate (pr-readiness.md) — change-path classification and the mutation-evidence freshness model that gate agent-led PR creation
Adversarial verification — an independent node tries to refute every finding against the actual code before it reaches the report
One ranked report (workflow-template.md) — per-lens verdicts, confirmed findings with file:line evidence, surfaced cross-lens conflicts, one recommendation

Built on graph-engineering for the generic node/topology/runtime machinery. There is deliberately no /pr command anymore: PR creation is ordinary agent-led work gated by the readiness reference above.

🎨 Impeccable Design → impeccable.style

Problem it solves: UI that looks generic or "AI-generated", inconsistent design quality, lack of systematic design methodology

What's inside (1 core skill + 9 reference files + 17 steering commands):

A comprehensive frontend design vocabulary and quality system from Paul Bakaus, replacing the original frontend-design skill with a much deeper methodology. The installer selects the declared skill names from reviewed commit 5d10bc8. Licensed under the Apache 2.0 License. Full documentation at impeccable.style/skills.

Getting Started: Design Context

Every impeccable skill checks for project design context before doing work. Without it, output is generic. Run this once per project:

/impeccable teach

This interviews you about your target audience, use cases, and brand personality, then saves the context to .impeccable.md in your project root. All design skills read this file automatically.

If you skip this step, any design command will prompt you to run /impeccable teach first.

Building Features: The Craft Flow

For new features that need both UX planning and implementation:

/impeccable craft [feature description]

This runs a structured 5-step flow:

Shape (/shape) - Produces a design brief through a discovery interview: purpose, content, design goals, constraints, anti-goals. No code is written. The brief becomes the blueprint for every implementation decision.
Load references - Based on the brief's needs, relevant deep-dive guides are loaded:
- typography.md - OpenType features, modular scales, font pairing, web font loading
- color-and-contrast.md - OKLCH color model, tinted neutrals, dark mode, accessibility
- spatial-design.md - 4pt spacing systems, grids, container queries, optical adjustments
- motion-design.md - Easing curves (no bounce/elastic), staggering, reduced motion
- interaction-design.md - 8 interactive states, focus rings, forms, modals, popovers
- responsive-design.md - Mobile-first, input method detection, safe areas
- ux-writing.md - Button labels, error formulas, empty states, translation planning
Build - Implements the feature following the brief, working through structure → layout → typography → interactive states → edge cases → motion → responsive.
Visual iteration - Reviews the live result against the brief and the AI Slop Test. Checks every state (empty, error, loading, edge cases). Iterates until the result matches the design intent.
Present - Shows the feature, walks through key states, explains design decisions that connect back to the brief, and asks for feedback.

You can also run /shape independently when you want UX planning without implementation.

Steering Commands: Targeted Improvements

Use these any time to make specific improvements. Each one checks for design context first.

Planning & Adaptation:

Command	What it does
`/shape`	Plan UX/UI before code. Produces a structured design brief through a discovery interview. Does NOT write code.
`/adapt`	Adapt designs across screen sizes, devices, contexts, or platforms. Covers mobile, tablet, desktop, print, and email.

Typography & Color:

Command	What it does
`/typeset`	Fix typography: font selection (with a 4-step process that fights AI defaults), hierarchy, readability, OpenType features, weight consistency.
`/colorize`	Add strategic color to monochromatic designs using the OKLCH color model. Covers semantic color, accent application, surfaces, data visualization.

Layout & Motion:

Command	What it does
`/layout`	Fix layout, spacing, and visual rhythm. Covers spacing systems, grid/flexbox selection, card grid monotony, depth/elevation, optical adjustments.
`/animate`	Add purposeful animations and micro-interactions. Specific easing curves and timing recommendations. Covers entrance animations, state transitions, feedback, delight moments.

Content & Copy:

Command	What it does
`/clarify`	Improve UX copy: error messages, form labels, buttons/CTAs, help text, empty states, success messages, loading states, confirmation dialogs.

Quality & Review:

Command	What it does
`/critique`	Full UX design review. Two-phase assessment using Nielsen's 10 heuristics (scored 0-40), cognitive load analysis, and persona-based testing across 5 user archetypes. Produces a scored report with severity ratings (P0-P3) and actionable recommendations mapped to other steering commands.
`/audit`	Technical quality checks. Scores 5 dimensions (Accessibility, Performance, Theming, Responsive, Anti-Patterns) on a 0-4 scale. Produces actionable recommendations.
`/polish`	Final quality pass. Comprehensive checklist covering design system consistency, visual alignment, typography refinement, color/contrast, interaction states, micro-interactions, content/copy, edge cases, responsiveness, performance, code quality.
`/harden`	Production-ready hardening. Text overflow/wrapping, i18n (RTL, CJK, translations), error handling, edge cases, onboarding/first-run, input validation, accessibility resilience, performance resilience.

Intensity Tuning:

Command	What it does
`/bolder`	Amplify designs that feel too safe or boring. Typography amplification, color intensification, spatial drama, visual effects, motion, composition boldness. Includes explicit warnings against falling into AI slop traps.
`/quieter`	Tone down designs that feel too aggressive. Color refinement, visual weight reduction, simplification, motion reduction, composition refinement.

Simplification & Personality:

Command	What it does
`/distill`	Strip to essence. Information architecture, visual, layout, interaction, content, and code simplification.
`/delight`	Add moments of joy and personality. Micro-interactions, personality in copy, illustrations, satisfying interactions, celebration moments, easter eggs.
`/optimize`	Frontend performance improvements. Loading, rendering, animation, framework optimization, network, Core Web Vitals (LCP, INP, CLS).
`/overdrive`	Technically extraordinary effects. Shaders, spring physics, scroll-driven reveals, View Transitions API, WebGL/WebGPU, virtual scrolling. Proposes directions before building.

Extracting Reusable Patterns

Once you have established patterns in your codebase:

/impeccable extract [target]

This discovers your design system structure, identifies components used 3+ times, hard-coded values that should be tokens, and inconsistent variations. It then extracts improved, reusable versions with proper TypeScript types, accessibility, and documentation.

Recommended Workflow for Frontend Development

/impeccable teach             Set up design context (once per project)
    │
    ▼
/shape [feature]              Plan UX/UI - produces a design brief
    │
    ▼
/impeccable craft [feature]   Build with full methodology (or build manually)
    │
    ▼
/critique                     UX review with Nielsen's heuristics (scored 0-40)
    │
    ▼
/polish                       Final quality pass
    │
    ▼
/harden                       Production hardening (i18n, edge cases, overflow)
    │
    ▼
/impeccable extract           Pull reusable components into design system

Use steering commands (/typeset, /colorize, /layout, /animate, etc.) at any point during development for targeted improvements.

Key Concepts

Context Gathering Protocol - Every design skill checks for project context before proceeding. It looks for a Design Context section in your loaded instructions, then checks .impeccable.md in the project root, and if neither exists, forces /impeccable teach. This ensures you never get generic output.
AI Slop Test - A structured checklist built into the craft flow to detect generic AI aesthetics: purple-to-blue gradients, Inter/Roboto font defaults, glassmorphism, bounce/elastic easing, dark mode with neon accents, side-stripe borders, gradient text. The skill actively fights these patterns.
Absolute Bans - Two CSS patterns are never acceptable: side-stripe borders (border-left/border-right > 1px on cards/callouts) and gradient text (background-clip: text with gradients). These are treated as hard failures, not style preferences.
Reference Library - 9 deep-dive reference files loaded on-demand when relevant. These contain specific CSS examples, technique catalogs, and decision frameworks for typography (OpenType, font loading, modular scales), color (OKLCH, tinted neutrals, dark mode), spatial design (4pt grid, container queries), motion (easing curves, staggering, reduced motion), interactions (8 states, focus rings, popovers), responsive design (input method detection, safe areas), and UX writing (error formulas, translation planning).

Attribution: impeccable by Paul Bakaus (GitHub), licensed under Apache 2.0. Based on Anthropic's original frontend-design skill. See the pinned NOTICE for full attribution.

🔥 Grill Me (optional external) → skills.sh/mattpocock/skills/grill-me

Problem it solves: Plans and designs that sound plausible but need ruthless pre-implementation questioning before they become expensive to change

What's inside: A focused external skill from Matt Pocock's skills repo that interviews you one question at a time until the plan, design tree, and decision dependencies are clear.

Use it when you want the assistant to:

Stress-test a plan or design branch-by-branch
Ask the next most important unresolved question, not a long checklist
Explore the codebase first when code context can answer the question
Provide a recommended answer with each question

Example prompt:

Use grill-me on this checkout refactor plan before I start implementation.

Use find-gaps when you want confirmed answers written back into an existing plan, acceptance criteria, or mock spec. When grill-me is not installed, use the first-party specification skill's one-question protocol.

🎯 Why These Skills Are Different

Unlike typical style guides, these skills provide:

Decision frameworks - Concrete questions to answer before taking action (not vague principles)
Priority classifications - Objective severity levels to prevent over/under-engineering
Anti-pattern catalogs - Side-by-side good/bad examples showing exactly what to avoid
Git verification methods - How to audit compliance after the fact
Quality gates - Verifiable checklists before commits
Problem-oriented - Organized by the problems you face, not abstract concepts

Most valuable insight across all skills: Abstract based on semantic meaning (what code represents), not structural similarity (what code looks like). This single principle prevents most bad abstractions.

Schema-First Decision Framework Example

One of the most valuable additions is a boundary framework for when runtime schemas are required:

// ✅ Schema REQUIRED - Trust boundary (API response)
const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email() });
const user = UserSchema.parse(apiResponse);

// ❌ Schema OPTIONAL - Pure internal type
type Point = { readonly x: number; readonly y: number };

Ask yourself:

Does untrusted data cross a runtime boundary? → Validate with a schema
Is it exchanged between independently deployed systems? → Validate at ingress/egress
Does a production schema already fit a contract-shaped fixture? → Reuse it when useful
Is it a trusted internal invariant? → A type, smart constructor, or domain value may be enough

🤖 Claude Code Agents: Automated Enforcement

→ Read the agents documentation

Nine specialized sub-agents that run in isolated context windows to enforce CLAUDE.md principles and manage development workflow:

1. `tdd-guardian` - TDD Compliance Enforcer

Use proactively when planning new or changed behavior, or reactively to verify that behavior followed TDD. Pure preservation work routes to refactor-scan or reduce-system-complexity instead.

What it checks:

✅ Behavior tests were written before new or changed production behavior
✅ Preservation-only work has a passing proportionate baseline rather than fabricated RED
✅ Tests verify behavior (not implementation)
✅ Changed and high-risk behavior has the repository-required coverage or proportionate alternate evidence
✅ Tests use the public interface at the layer named by each claim
✅ TDD chronology is reported as indeterminate unless a failing-run receipt exists
❌ Flags implementation-focused tests
❌ Catches missing edge case tests

Example invocation:

You: "I just implemented payment validation. Can you check TDD compliance?"
Claude Code: [Launches tdd-guardian agent]

Output:

Lists all TDD violations with file locations
Identifies implementation-focused tests
Suggests missing test cases
Provides actionable recommendations

2. `ts-enforcer` - TypeScript Strict Mode Enforcer

Use before commits or when adding new types/schemas.

What it checks:

❌ Unexplained or leaking any; narrow unavoidable interop is allowed
❌ Type assertions without justification
✅ Repository convention and language semantics for type/interface
✅ Runtime schemas at untrusted boundaries
✅ Declared immutability contracts
✅ Options objects where positional arguments are ambiguous

Includes the nuanced schema-first framework:

Schema required: Untrusted runtime boundaries and independently deployed contracts
Schema reused when useful: Existing production contracts exercised by tests
Schema optional: Trusted internal invariants, utilities, state machines, and behavior contracts

Example invocation:

You: "I've added new TypeScript code. Check for type safety violations."
Claude Code: [Launches ts-enforcer agent]

Output:

Critical violations (any types, missing schemas at boundaries)
High priority issues (mutations, poor structure)
Style improvements (naming, parameter patterns)
Compliance score with specific fixes

3. `refactor-scan` - Refactoring Opportunity Scanner

Use after GREEN establishes a passing behavior-test baseline (the applicable REFACTOR step in the change workflow). Mutation testing verifies the accumulated result later at PR readiness.

What it analyzes:

🎯 Knowledge duplication (DRY violations)
🎯 Semantic vs structural similarity
🎯 Complex nested conditionals
🎯 Magic numbers and unclear names
🎯 Immutability violations

What it doesn't recommend:

❌ Refactoring code that's already clean
❌ Abstracting structurally similar but semantically different code
❌ Cosmetic changes without clear value

Example invocation:

You: "My tests are passing, should I refactor anything?"
Claude Code: [Launches refactor-scan agent]

Output:

🔴 Critical refactoring needed (must fix)
⚠️ High value opportunities (should fix)
💡 Nice to have improvements (consider)
✅ Correctly separated code (keep as-is)
Specific recommendations with code examples

4. `docs-guardian` - Documentation Quality Guardian

Use proactively when creating documentation or reactively to review and improve existing docs.

What it ensures:

✅ A clear page job, audience, owner, and current authority
✅ The lightest structure that serves that document type
✅ Material capability, current-state, command, code, and link claims are checked
✅ Lasting facts are routed to their durable owner
✅ Navigation, examples, cross-references, and next steps only where useful

What it checks:

❌ Wall of text without visual breaks
❌ Feature lists without value demonstrations
❌ Installation-first (before showing what it does)
❌ Missing navigation aids
❌ Broken links or outdated information

Example invocation:

You: "I need to write a README for this feature."
Claude Code: [Launches docs-guardian agent]

You: "Can you review the documentation I just wrote?"
Claude Code: [Launches docs-guardian agent]

Output:

Assessment against the canonical technical-writing guidance and page job
Critical issues (must fix) vs nice-to-haves
Specific improvement recommendations with examples
The smallest useful edit or restructuring for the owned document

5. `learn` - Durable Learning Router

Use proactively when discovering gotchas, or reactively after completing complex features.

What it routes:

Gotchas or unexpected behavior discovered
"Aha!" moments or breakthroughs
Accepted architectural decisions and their trade-offs
Patterns that worked particularly well
Anti-patterns encountered
Tooling or setup knowledge gained

Example invocation:

You: "I just fixed a tricky timezone bug. Let me document this gotcha."
Claude Code: [Launches learn agent]

Output:

Evidence, scope, and recurrence risk for the learning
The existing owner or smallest appropriate destination
An update to source/tests, a glossary, decision mechanism, maintained docs, active plan, or repository policy when writing is authorized
CLAUDE.md only when it is the declared owner of local working policy

6. `progress-guardian` - Progress Guardian

Use proactively when starting significant vertical-slice work, or reactively to track progress through plan slices.

What it manages:

Tracks progress through vertical slices in the repository's plan owner (plans/<name>.md only as the fallback)
Enforces small increments, TDD, and commit approval
Never modifies plans without explicit user approval
At end: orchestrates learning routing, then follows the plan owner's close/archive/delete lifecycle; deletion is only the fallback temporary-file lifecycle and still requires normal authority

Example invocation:

You: "I need to implement OAuth with JWT tokens and refresh logic"
Claude Code: [Launches progress-guardian to update the repository plan owner]

You: "Tests are passing now"
Claude Code: [Launches progress-guardian to update plan and ask for commit approval]

Output:

Repository-owned plan artifact with approved slices and acceptance criteria
At end: durable facts routed to their owners, then the temporary plan closed or deleted

Key distinction: Plan files are temporary. Move lasting truth to its actual owner before closing the plan; Git preserves plan history.

Related skill: Load planning skill for detailed incremental work principles.

7. `adr` - Architecture Decision Records

Use proactively when making significant architectural decisions, or reactively to document decisions already made.

What it documents:

Significant architectural choices with trade-offs
Technology/library selections with long-term impact
Pattern decisions affecting multiple modules
Performance vs maintainability trade-offs
Security architecture decisions

When to use:

✅ Evaluated multiple alternatives with trade-offs
✅ One-way door decisions (hard to reverse)
✅ Foundational choices affecting future architecture
❌ Trivial implementation choices
❌ Temporary workarounds
❌ Practices already owned by canonical skills or repository policy

Example invocation:

You: "Should we use BullMQ or AWS SQS for our job queue?"
Claude Code: [Launches adr agent to help evaluate and document]

You: "I decided to use PostgreSQL over MongoDB"
Claude Code: [Launches adr agent to document the rationale]

Output:

Accepted record in the repository's declared decision mechanism, using docs/adr/ only as a fallback when an ADR was requested and no owner exists
Honest assessment of pros/cons and trade-offs
Clear rationale for decision
Consequences (positive, negative, neutral)
Updated ADR index

Key distinction: ADRs record accepted architectural choices and their trade-offs; learn routes operational knowledge to whatever source owns it.

8. `use-case-data-patterns` - Use Case to Data Pattern Analyzer

Use proactively when implementing features, or reactively to understand how features work end-to-end.

What it analyzes:

Maps user-facing use cases to underlying data patterns
Traces features through system architecture
Identifies gaps in data access patterns

Example invocation:

You: "How does the checkout flow work from user click to database?"
Claude Code: [Launches use-case-data-patterns agent]

Output:

Evidence-labelled trace from actor trigger to observable result
Exact owners and locations for policy, domain logic, data, effects, and failure handling
Only material correctness, authorization, integrity, concurrency, delivery, recovery, or operability gaps

The current agent is an original rewrite. Its source notes disclose an earlier unlicensed copy and the unresolved published-history issue.

9. `twelve-factor-audit` - Twelve-Factor Compliance Auditor

Use when onboarding to a service project, assessing deployment readiness, or reviewing infrastructure patterns.

What it audits (all 12 factors):

Factor	What It Checks
I. Codebase	Single repo, multiple deploys
II. Dependencies	Explicit declaration, lockfile committed
III. Config	External runtime injection, centralized validation, no hardcoded secrets
IV. Backing Services	Injected platform resource bindings (URLs are one common form)
V. Build/Release/Run	Distinct build, release configuration, and run stages in the declared platform workflow
VI. Processes	Disposable execution with durable state externalized where the workload requires it
VII. Port Binding	Self-contained service binding or the platform's equivalent handler contract
VIII. Concurrency	Scale through the platform's applicable process, function, job, or worker units
IX. Disposability	Fast start and bounded graceful shutdown; probes and draining only where the platform owns them
X. Dev/Prod Parity	Minimized time, personnel, tooling, and backing-service contract differences
XI. Logs	Structured platform-captured process streams, no file transports
XII. Admin Processes	One-off processes run from the same release with the same injected config

Example invocation:

You: "Audit this service for 12-factor compliance"
Claude Code: [Launches twelve-factor-audit agent, produces compliance report]

Output:

Factor summary table with compliance status
Detailed findings with file paths and line numbers
Code suggestions for each gap
Prioritized action plan

Related skill: Load twelve-factor skill for detailed 12-factor patterns.

⚡ Slash Commands

→ Browse the commands directory

Three slash commands that encode common workflows into single invocations:

Command	Purpose	When to Use
`/setup`	Authorized project onboarding — detect tech stack, create project guidance, hooks, and commands	Only when the user explicitly requests onboarding/config generation
`/plan`	Create a plan document on a branch with a PR — no code changes	When planning work before implementation
`/continue`	Continue after a merged independent PR or advance/sync a stack	Moving to the next slice or dependent layer

PR review is not a command: the panel-review skill provides /panel-review, and PR creation is ordinary agent-led work gated by that skill's PR-readiness reference.

Recommended Flow

This is the delivery lifecycle for a feature. Project setup is a separate, one-time action used only when explicitly requested.

Optional Project Setup (once per project, with explicit authorization)

/setup  →  Detects tech stack, creates .claude/CLAUDE.md, hooks, and commands

When explicitly onboarding: /setup replaces Claude Code's built-in /init. With authorization to create project configuration, it analyses the TypeScript config, CI pipeline, DDD patterns, and test runner, then creates:

.claude/CLAUDE.md with exact build/test/lint/typecheck commands
.claude/settings.json with PostToolUse hooks (auto-typecheck after file edits)

Code reviews need no project-generated automation: /setup points reviews at the global panel-review skill, which auto-detects project traits (hexagonal, DDD, React, ...) and composes matching skill lenses at review time.

Phase 1: Plan the Work (before writing any code)

/plan  →  Uses the repository's plan owner; falls back to plans/ + a plan-only PR when none is declared

Why before code: Planning in a separate phase prevents the most common friction point — Claude jumping straight to implementation before the approach is agreed. The plan becomes a PR you can review and approve before any code is written. Each slice defaults to one trunk-based PR; stack-pull-requests may add review layers inside one slice or link hard-/flow-lineage vertical slices when work should proceed before lower reviews merge.

Phase 3: Implement (repeat fast increments within each slice or PR boundary)

LOAD         →  Behavior change: tdd + testing + refactoring; preservation: applicable testing/refactoring/reduction skills
RED          →  For changed behavior, write a failing behavior test (tdd-guardian verifies test-first)
GREEN        →  Write minimum code to pass (ts-enforcer checks type safety)
REFACTOR / REDUCE →  Run only the applicable assessment and any claimed reduction gates
COMMIT       →  Wait for approval, then commit

Why this order: RED-GREEN-REFACTOR keeps implementation feedback fast. The mutation harness does not run after each test, increment, refactor, or commit; it runs once when the current review boundary is otherwise PR-ready. Pure refactors or reductions enter at a passing proportionate-evidence path rather than inventing RED or structural mutants. Tests stay with the earliest PR boundary that owns their behavior.

Phase 4: Pre-PR Quality Gate

Before creating any PR, work through the readiness gate (owned by the panel-review skill's PR-readiness reference), then review:

PR readiness gate →
  1. phase complete    →  Verify implementation and applicable refactoring/reduction work are finished
  2. mutation gate     →  Run mutation testing once against trunk or the immediate stack parent, or record explicit `N/A` plus proportionate alternate evidence
  3. survivor handling →  Address valuable survivors; re-run focused/diff mutation checks inside the same gate
  4. remaining checks  →  Run typecheck + lint + test + build, then create the PR (ordinary agent-led work — no dedicated command)

/panel-review →  Multi-agent review of the boundary — every lens is an installed skill, findings adversarially verified into one ranked report

Why evidence at PR readiness: One focused run per review boundary verifies that the completed implementation and refactoring would catch behavioral faults without taxing every inner TDD loop. A stacked boundary uses its immediate parent as the review base; the top proves the cumulative criteria for every included slice. When the affected mechanism is unreachable, declarative, contractual, integrational, or operational, an explicit N/A plus proportionate alternate evidence is more honest. The /panel-review readiness lens re-checks this same gate adversarially during review.

Phase 5: Continue

Independent slice →  /continue updates trunk and creates the next independent branch
Stack              →  /continue adds a dependent layer or slice from the current top, or syncs after lower merges

Why a command for this: Independent slices return to trunk. Stacked PRs keep an explicit parent branch until bottom-up merge and sync, whether a PR owns a whole dependent slice or an intra-slice layer. /continue reads the delivery map before choosing either topology.

Phase 6: Capture Knowledge (throughout and at the end)

learn agent       →  Routes durable learnings to their actual owners
adr agent         →  Documents significant architectural decisions
docs-guardian     →  Updates user-facing documentation

Why at the end: Use learn to route durable facts to their actual owners, adr for accepted architectural decisions, and docs-guardian only for maintained pages affected by the change.

🚀 How to Use This in Your Projects

Quick navigation by situation:

Your Situation	Recommended Option
"I want this on all my personal projects"	Option 1: Global Install
"I'm setting this up for my team"	Option 2: Project-specific install
"I just want to try the guidelines first"	Option 3: CLAUDE.md only
"I need to customize for my team's standards"	Option 4: Fork and customize

How the Workflow Works (Regardless of Installation Method)

Once installed, the normal delivery lifecycle is: /plan → single-PR or stack delivery → fast RED-GREEN-REFACTOR or preservation increments → end-of-boundary evidence gate from the panel-review skill's PR-readiness reference → agent-led PR creation and /panel-review for review → /continue → repeat. /setup is separate and runs only for explicitly authorized project onboarding. See the Recommended Flow for details.

Agent invocation examples:

Agents are invoked implicitly (Claude detects when to use them) or explicitly:

Implicit: "I just implemented payment processing. Can you verify I followed TDD?" → Claude automatically launches tdd-guardian
Explicit: "Launch the refactor-scan agent to assess code quality" → Claude launches refactor-scan
Multiple agents: "Run TDD, TypeScript, and refactoring checks on my recent changes" → Claude launches all three in parallel

Now choose your installation method:

Option 1: Install to ~/.claude/ (Global Personal Config) ⭐ RECOMMENDED

Best for: Individual developers who want consistent practices across all projects

Why choose this:

✅ One-time setup applies everywhere automatically
✅ No per-project configuration needed
✅ Skills install via skills.sh — works with Claude Code, Cursor, Codex, Copilot, OpenCode, Gemini CLI, and 40+ other agents
✅ Modular structure loads details on-demand
✅ Explicit maintenance: inspect with npx skills@1.5.22 list -g; reviewed installer reruns back up selected skills before replacement, and git pull updates the checkout

Install from an inspected, immutable checkout:

git clone https://github.com/citypaul/.dotfiles.git citypaul-dotfiles
cd citypaul-dotfiles
INSTALLER_REF=$(git rev-parse HEAD)
git switch --detach "$INSTALLER_REF"
less install-claude.sh                    # inspect before execution
./install-claude.sh --version "$INSTALLER_REF"

The checkout is downloaded but not executed until you inspect it. Capturing HEAD before execution pins first-party downloads and skill installation to that exact commit. Review source changes before choosing a newer commit; do not pipe a moving main script into a shell.

Install options:

./install-claude.sh                                      # Install everything (CLAUDE.md + skills + commands + agents)
./install-claude.sh --claude-only                        # Install only CLAUDE.md
./install-claude.sh --skills-only                        # Install only skills (via skills.sh)
./install-claude.sh --no-agents                          # Install without agents
./install-claude.sh --no-external                        # Skip all external community skills (web-quality-skills + next-skills + impeccable + grill-me + seo-audit + herdr)
./install-claude.sh --no-impeccable                      # Skip impeccable design skills only
./install-claude.sh --no-ponytail                        # Skip the ponytail plugin (https://ponytail.dev, Claude Code + Codex)
./install-claude.sh --with-opencode                      # Also target OpenCode for skills + install OpenCode config
./install-claude.sh --agent codex --agent cursor         # Also install skills for Codex and Cursor (repeatable)
./install-claude.sh --skills-only --no-claude-code \     # Install skills ONLY for a non-Claude agent
                    --agent codex
./install-claude.sh --version <reviewed-tag-or-commit>   # Pin first-party artifacts; moving refs are rejected

Targeting other agents:

Skills.sh supports 40+ coding agents (Claude Code, Cursor, Codex, Copilot, OpenCode, Gemini CLI, Cline, Continue, Windsurf, …). Use --agent <name> (repeatable) to add extra targets alongside the default claude-code. Use --no-claude-code with --agent to target only non-Claude agents. After install, npx skills@1.5.22 list -g shows which skills each agent can see.

The skills CLI installs the complete skill directory, not just SKILL.md. Companion files such as agents/openai.yaml, references/, scripts/, and assets/ therefore travel with the skill. For structure-codebase, Codex receives its interface metadata at agents/openai.yaml without a separate installation step.

This installer passes --copy to the pinned CLI explicitly. The destination depends on the selected agents:

A universal agent (Codex, OpenCode, and others whose global target is .agents/skills) gets a copy under ~/.agents/skills/<name>/; that shared path is the agent's read path.
A per-agent client (Claude Code, Continue, Windsurf, …) gets a copy in its own skills directory, such as ~/.claude/skills/<name>/.
Multiple selected targets receive separate copies in their resolved global directories; no hidden canonical directory is written for a non-universal target.

All three layouts expose the same complete bundle. Include --agent codex when Codex should discover and use the skill (the installer targets Claude Code only by default).

Repeat installs are recoverable. Before invoking the CLI, the installer copies every existing selected skill to an adjacent skills.before-install.<random>/ directory. The pinned CLI can then refresh those reviewed names without unrelated skills or files blocking the install.

What gets installed:

✅ ~/.claude/CLAUDE.md (~160 lines - lean core principles)
✅ ~/.claude/skills/ — installed via skills.sh with npx skills@1.5.22 add; every source revision and selected skill name is explicit:
- citypaul/.dotfiles — auto-discovered first-party patterns (tdd, testing, mutation-testing, typescript-strict, functional, refactoring, planning, story-splitting, stack-pull-requests, front-end-testing, react-testing, event-sourcing, and more)
- pbakaus/impeccable — frontend design vocabulary + 17 steering commands
- addyosmani/web-quality-skills — accessibility, performance, SEO, core-web-vitals, best-practices, web-quality-audit
- vercel-labs/next-skills — Next.js best practices, Cache Components, and upgrade workflow
- mattpocock/skills/grill-me — one-question-at-a-time plan and design interrogation
- coreyhaines31/marketingskills/seo-audit — technical, on-page, content, and authority SEO audit workflow
- herdrdev/herdr — drive the Herdr terminal workspace from inside an agent: split panes, run commands, read output, wait on a sibling agent
✅ ~/.claude/commands/ (3 slash commands: /setup, /plan, /continue)
✅ ~/.claude/agents/ (9 specialized workflow agents)

Inspecting skills after install:

npx skills@1.5.22 list -g              # List installed skills
npx skills@1.5.22 find <query>         # Discover more skills on skills.sh

The CLI's update and remove commands mutate destinations without this installer's automatic selected-skill backup. Do not run them as routine maintenance: first back up the exact targets, prove they are CLI-owned, and review the resolved source bytes. The conservative path is a reviewed installer rerun. To update a pinned source, review its diff, change the exact commit in this repository, and run the installer tests before release.

Requires Node.js for skills install (so npx is available). Use --claude-only or --agents-only if you don't have Node installed.

Why does the installer use skills.sh instead of curling skills directly?

The installer used to curl every SKILL.md straight from this repo into ~/.claude/skills/. It worked, but it was Claude-Code-only and the file list lived inside the installer. Switching skill installs to the pinned skills.sh CLI changes four things:

Multi-agent portability. The same skills are now installable against 40+ coding agents — Claude Code, Cursor, Codex, GitHub Copilot, OpenCode, Gemini CLI, Cline, Continue, Windsurf, and more — via the -a <agent> flag. Using these skills from a non-Claude tool no longer requires a Claude-specific copy step. --with-opencode is now just an extra -a opencode on the existing install instead of a second duplicated tree.
Inspection and discovery commands. npx skills@1.5.22 list -g records what the shared lock knows, and find <query> surfaces skills beyond this repo. Mutating update/remove commands bypass this installer's automatic backup, so they require an explicit backup, ownership check, and source review rather than being advertised as safe routine lifecycle operations.
Explicit target copies. The installer passes --copy, so installation writes only the selected agents' resolved global targets. The shared lock records source metadata but does not prove ownership of any destination.
Installer doesn't grow with the skill list. Three curl loops with hard-coded file lists (including every resources/*.md and references/*.md) collapsed to a small set of pinned CLI calls. Adding a new skill to claude/.claude/skills/ no longer requires a matching installer edit — the CLI discovers it.
Recoverable repeat installs. Setup copies existing selected skill names to an adjacent backup before replacement. Unselected content stays untouched, and a failed CLI install leaves the previous copy available for recovery.

Trade-offs:

Requires Node.js for npx. --claude-only and --agents-only still work without it.
The executable CLI is pinned to skills@1.5.22. Every repository source is pinned to a commit, and the installer hands each pin to the CLI as a GitHub commit-archive URL (the CLI's #<git-ref> syntax clones with git clone --branch, which rejects commit SHAs). Every selected skill name is declared before installation; source changes require an explicit pin update and re-audit. --version pins first-party skills, CLAUDE.md, commands, and agents to the same reviewed release/commit.
Skills used to ship at the same v3.x tag as everything else in this repo; now they roll independently. Use npx skills@1.5.22 list -g --json if you want to snapshot what's installed.

CLAUDE.md, slash commands, and Claude-Code agents are still curled directly from this repo — they aren't skills and aren't part of the skills.sh ecosystem.

Optional: Enable GitHub MCP Integration

For enhanced GitHub workflows with native PR/issue integration:

Step 1: Create a GitHub Personal Access Token

Go to https://github.com/settings/tokens and create a token:

For Fine-grained token (recommended):

Repository access: All repositories (or select specific ones)
Permissions required:
- Contents: Read and write
- Pull requests: Read and write
- Issues: Read and write
- Metadata: Read-only (automatically included)

For Classic token:

Select the repo scope (full control of private repositories)

Step 2: Add the MCP Server

claude mcp add --transport http --scope user github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

Replace YOUR_GITHUB_TOKEN with the token you created.

Step 3: Verify Connection

Restart Claude Code and run /mcp to verify the GitHub server shows as connected.

What this enables:

Native PR creation, updates, and reviews
Issue management without CLI parsing
Structured GitHub API access
@github:pr://123 - Reference PRs directly in prompts
@github:issue://45 - Reference issues directly in prompts

Optional: Enable OpenCode Support

These guidelines also work with OpenCode - an open source AI coding agent. All slash commands, agents, and skills work in both Claude Code and OpenCode.

How OpenCode Integration Works:

OpenCode doesn't automatically read ~/.claude/ files. It uses different discovery paths:

Component	Claude Code	OpenCode	Integration
Instructions	`~/.claude/CLAUDE.md`	`~/.config/opencode/AGENTS.md`	`opencode.json` instructions field
Skills	`~/.claude/skills/`	Native compatibility discovery	Loaded on demand; never injected globally through `instructions`
Commands	Pinned repository manifest	`~/.config/opencode/command/` (singular)	Declared files copied with frontmatter converted
Agents	Pinned repository manifest	`~/.config/opencode/agent/` (singular)	Declared files copied with frontmatter converted

The installer projects only its declared command and agent manifests from the pinned repository source. It strips incompatible Claude Code frontmatter fields and backs up every pre-existing OpenCode destination before replacement; it never enumerates unrelated local ~/.claude files. OpenCode discovers skills and projected agents through their native mechanisms rather than injecting every definition into each session.

Installation:

# From the inspected detached checkout in Option 1
INSTALLER_REF=$(git rev-parse HEAD)
./install-claude.sh --version "$INSTALLER_REF" --with-opencode

# OpenCode config only (if CLAUDE.md is already installed)
./install-claude.sh --version "$INSTALLER_REF" --opencode-only

What gets installed:

~/.config/opencode/opencode.json - Configuration that enables built-in LSP servers, including TypeScript for projects with a TypeScript dependency, and loads only ~/.claude/CLAUDE.md as global instructions
Skills remain available through OpenCode's native on-demand compatibility discovery; projected agents remain named agent definitions rather than global instructions
~/.config/opencode/command/ - Declared slash-command manifest from the pinned source (frontmatter converted)
~/.config/opencode/agent/ - Declared agent manifest from the pinned source (frontmatter converted)

Manual Installation:

Use the inspected pinned installer above. Do not replace it with a glob-based copy: the explicit manifest, transformation, and per-destination backup are one reviewed operation and prevent unrelated local files from being projected or existing OpenCode files from being silently overwritten.

Learn more:

Option 2: Use CLAUDE.md + Agents (Recommended for Projects)

Best for: Team projects where you want full control and project-specific configuration

Why choose this:

✅ Full enforcement in a specific project
✅ Team can collaborate on customizations
✅ Version control with your project
✅ Works without global installation

For full enforcement in a specific project, install both CLAUDE.md and the agents:

# From the inspected detached checkout in Option 1, while in your project root
mkdir -p .claude/agents .claude/commands
cp /path/to/citypaul-dotfiles/claude/.claude/CLAUDE.md .claude/
cp /path/to/citypaul-dotfiles/claude/.claude/agents/*.md .claude/agents/
cp /path/to/citypaul-dotfiles/claude/.claude/commands/*.md .claude/commands/

Option 3: Use CLAUDE.md Only - Single File (v1.0.0)

Best for: Quick evaluation or when you want everything in one standalone file

Why choose this:

✅ Single command, one file (1,818 lines)
✅ All content included - examples, anti-patterns, decision frameworks
✅ Works standalone (no broken imports)
✅ No agent overhead
⚠️ Tradeoff: Larger file vs v2.0.0's modular structure (156 lines + separate docs)
⚠️ Tradeoff: Uses v1.0.0 structure (content identical to v2.0.0, just organized differently)

Important: This downloads the historical v1.0.0 monolithic version. The current package (4.9.0) uses the v3 architecture generation: a self-contained core with skills loaded on demand. For project-level use, prefer an inspected current release or commit rather than the obsolete v3.0.0 tag.

Download the complete single-file version:

# In your project root
mkdir -p .claude
curl -o .claude/CLAUDE.md https://raw.githubusercontent.com/citypaul/.dotfiles/v1.0.0/claude/.claude/CLAUDE.md

This gives you the complete guidelines (1,818 lines) in a single standalone file.

Option 4: Fork and Customize (Advanced)

Best for: Teams with specific standards who need full customization control

Why choose this:

✅ Complete control over guidelines and enforcement
✅ Customize for your team's specific tech stack
✅ Modify agent behavior to match your workflow
✅ Maintain team-specific patterns and anti-patterns

How to customize:

Fork this repository
Modify CLAUDE.md to match your team's preferences
Customize agents to enforce your specific rules
Commit to your fork
Pull into your projects

Architecture generations

Current package release (v4.9.0): Uses the v3 skills-based architecture with lean CLAUDE.md (~160 lines), auto-discovered skills, slash commands, and planning workflow.

The labels below describe historical architecture generations, not the current package version:

Legacy version (v1.0.0): Single monolithic file (1,818 lines, all-in-one)

Version	Architecture	Context Size	Best For
v3.0.0	Skills (on-demand)	~160 lines always	Context-efficient, truly lean
v2.0.0	@docs/ imports	~3000 lines always	Full docs always loaded
v1.0.0	Single file	~1800 lines always	Standalone, no dependencies

v3 architecture (current source browser; not an installer pin): claude/.claude
v2.0.0 modular docs: https://github.com/citypaul/.dotfiles/tree/v2.0.0/claude/.claude
v1.0.0 single file: https://github.com/citypaul/.dotfiles/blob/v1.0.0/claude/.claude/CLAUDE.md

The installer derives an exact commit from an inspected checkout, or requires an explicit reviewed release/commit with --version. It rejects moving refs and uses exact source revisions plus declared skill names; review and test every pin change before release.

📚 Documentation

CLAUDE.md - Core development principles (~160 lines)
Skills - Auto-discovered patterns from this repo, 6 from addyosmani/web-quality-skills, 3 from vercel-labs/next-skills, 18 from pbakaus/impeccable, optional grill-me from mattpocock/skills, seo-audit from coreyhaines31/marketingskills, and herdr from herdrdev/herdr — all installed via skills.sh for multi-agent portability.
Commands - Slash commands (/setup, /plan, /continue)
Agents README - Detailed agent documentation with examples
Agent Definitions - Individual agent configuration files (9 agents: tdd-guardian, ts-enforcer, refactor-scan, docs-guardian, learn, progress-guardian, adr, use-case-data-patterns, twelve-factor-audit)

🎯 Who This Is For

Teams adopting TDD - Automated enforcement prevents backsliding
TypeScript projects - Nuanced schema-first guidance with decision frameworks
AI-assisted development - Consistent quality with Claude Code or similar tools
Solo developers - Institutional knowledge that doesn't rely on memory
Code reviewers - Objective quality criteria and git verification methods

💡 Philosophy

This system is based on several key insights:

AI needs explicit context - Vague principles → inconsistent results. Decision frameworks → reliable outcomes.
Quality gates prevent drift - Automated checking catches violations before they become habits.
Refactoring needs priority - Not all improvements are equal. Critical/High/Nice/Skip classification prevents over-engineering.
Semantic beats structural - Abstract based on meaning (business concepts), not appearance (code structure).
Route learning while fresh - Capture evidence while context is available, then put durable knowledge with the source that can keep it true.
Explicit "no refactoring" - Saying "code is already clean" prevents the feeling that the refactor step was skipped.

🔄 Continuous Improvement

The guidance and its owning sources evolve from real usage. The learn agent routes valuable evidence instead of building a parallel knowledge dump:

Behavioral constraints → Source and executable tests
Domain terms → The bounded-context glossary
Reusable practices → Canonical global skills
Local working policy → Repository guidance such as CLAUDE.md when it owns it
Accepted architectural decisions → The repository's decision mechanism

This keeps each fact with one accountable owner while preserving useful learning from completed work.

📦 Personal Dotfiles (The Original Purpose)

While most visitors are here for CLAUDE.md, this repository's original purpose is managing my personal development environment. If you're interested in dotfiles, here's what's included and how to use them.

Git Aliases

I have an extensive collection of git aliases that speed up common workflows. These are in git/.gitconfig.

Most useful aliases:

# Pretty log with graph
git lg          # One-line log with graph
git lga         # All branches log with graph
git lgp         # Log with patch (shows changes)

# Status and diff shortcuts
git st          # git status
git di          # git diff
git dc          # git diff --cached
git ds          # git diff --stat

# Commit shortcuts
git ci          # git commit
git ca          # git commit --amend
git cane        # git commit --amend --no-edit

# Branch management
git co          # git checkout
git cob         # git checkout -b (new branch)
git br          # git branch
git brd         # git branch -d (delete branch)

# Working with remotes
git pu          # git push
git puf         # git push --force-with-lease (safer force push)
git pl          # git pull
git plo         # git pull origin

# Stash shortcuts
git sl          # git stash list
git ss          # git stash save
git sp          # git stash pop

# Undo shortcuts
git undo        # Undo last commit (keeps changes)
git unstage     # Unstage files
git uncommit    # Undo commit and unstage

# Advanced workflows
git wip         # Quick "work in progress" commit
git unwip       # Undo WIP commit
git squash      # Interactive rebase to squash commits

Installation:

# Install just the git config
cd ~/.dotfiles
stow git

# Or manually copy specific aliases you want
cat git/.gitconfig >> ~/.gitconfig

Shell Configuration

My shell setup (for bash/zsh) includes:

Prompt customization - Git status in prompt
Useful functions - Project navigation helpers
PATH management - Tool directories
Environment variables - Editor, pager, etc.

Files:

bash/.bashrc - Bash configuration
bash/.bash_profile - Bash login shell
zsh/.zshrc - Zsh configuration (if you use zsh)

Installation:

cd ~/.dotfiles
stow bash  # or stow zsh

Development Tools Configuration

Configuration files for various development tools:

vim/.vimrc - Vim editor configuration
tmux/.tmux.conf - Terminal multiplexer settings
npm/.npmrc - npm configuration

Claude Code Settings

The claude/.claude/settings.json file contains my personal Claude Code configuration including:

claude-powerline - vim-style statusline with usage tracking and git integration
Official Anthropic plugins - feature-dev, frontend-design, hookify, learning-output-style, plugin-dev, security-guidance

Installing Everything

⚠️ Important: This installs ALL personal dotfiles (git, shell, vim, etc.) NOT just CLAUDE.md

⚠️ Requires: GNU Stow must be installed first

For CLAUDE.md only (no stow needed), see Option 3 above.

To install all dotfiles including my personal configurations:

# Install GNU Stow first (if not already installed)
# macOS: brew install stow
# Ubuntu/Debian: sudo apt-get install stow
# Fedora: sudo dnf install stow

# Clone the repository
git clone https://github.com/citypaul/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Run the installation script
./install.sh

# This uses GNU Stow to create symlinks for all configurations

This will install:

✅ CLAUDE.md + first-party skills plus external skill bundles + 9 agents (development guidelines)
✅ Commands (/setup, /plan, /continue slash commands)
✅ Claude Code settings.json (plugins, hooks, statusline)
✅ OpenCode configuration (guidelines plus built-in LSP servers, including TypeScript)
✅ Git aliases and configuration
✅ Shell configuration (bash/zsh)
✅ Vim, tmux, npm configs
✅ All personal preferences

Installing Specific Dotfiles

⚠️ Requires: GNU Stow (see installation commands above)

Only want certain configurations? Install them individually:

cd ~/.dotfiles

# Install just git config
stow git

# Install just bash config
stow bash

# Install vim config
stow vim

# Install multiple at once
stow git bash vim

How Stow Works

This repository uses GNU Stow for dotfile management:

Each directory (git/, bash/, etc.) represents a "package"
Files inside mirror your home directory structure
stow git creates symlinks from ~/.gitconfig → ~/.dotfiles/git/.gitconfig
Changes to files in ~/.dotfiles are instantly reflected
Uninstall with stow -D git

Browsing the Dotfiles

Feel free to browse the repository and cherry-pick what's useful:

zsh/.zshrc - Zsh shell configuration
tmux/.tmux.conf - tmux configuration
alacritty/.alacritty.toml - Alacritty terminal configuration

Note: These are my personal preferences. Review before installing - you may want to customize them for your workflow.

🤝 Contributing

This is a personal repository that became unexpectedly popular. Contributions are welcome, especially:

Improvements to CLAUDE.md - Better decision frameworks, clearer examples
Agent enhancements - New checks, better error messages
Documentation - Clarifications, additional examples
Real-world feedback - What worked? What didn't?

Please open issues or PRs on GitHub.

📞 Contact

Paul Hammond

LinkedIn - Feel free to connect and discuss
GitHub Issues - Questions, suggestions, feedback

🙏 Acknowledgments

Special thanks to contributors who have shared their work:

Matt Pocock and John Ousterhout - The local codebase-design and improve-codebase-architecture skills are adapted from Matt's MIT-licensed original codebase-design/SKILL.md, DEEPENING.md, DESIGN-IT-TWICE.md, improve-codebase-architecture/SKILL.md, and HTML-REPORT.md at pinned commit 66898f60. Ousterhout's deep-module, information-hiding, complexity, and Design It Twice concepts provide the design foundation. Per-skill source notes and complete MIT notices preserve the detailed attribution chain and local departures.
Adam Bulmer - reduce-system-complexity is an attributed adaptation of Adam's MIT-licensed reducer/SKILL.md and companion agents/openai.yaml at pinned commit d698a88f. It retains the conservation ledger, whole-mechanism baseline, first-principles minimum, and dual evidence gates while documenting the rename, narrowed trigger, qualitative ranking, migration safeguards, and local testing/architecture integration. The original MIT license is preserved beside the adaptation. This repository also adapts Adam's wtf/SKILL.md at pinned commit e436942e, adding repository-owned glossary lookup while preserving the original MIT licence and source notes.

acceptance-review also adapts Adam's MIT-licensed criterion review workflow at pinned commit 976d4a0c, removing its unavailable sibling dependency and adding explicit authority and indeterminate-evidence handling.
Michael Feathers - The finding-seams and characterisation-tests skills are adapted from Working Effectively with Legacy Code (2004). Feathers' concepts of seams, enabling points, and characterization tests are foundational techniques for making untestable code testable. The skills adapt his C++/Java examples to modern TypeScript/JavaScript patterns.
Addy Osmani - The web quality skills (accessibility, best-practices, core-web-vitals, performance, seo, web-quality-audit) install from reviewed commit 95d6e25, under its MIT License. The api-design skill is adapted from Addy's MIT-licensed api-and-interface-design skill. Local history records no original upstream import revision, so 7676817c12a1317454ae3898a0c5c1eacf5dd3d5 is documented only as an immutable audit baseline; detailed source notes, local departures, and the upstream notice live beside the skill.
Corey Haines - The seo-audit skill and its references install from reviewed commit 7868cb9. Licensed under the pinned MIT License.
Vercel Labs - The Next.js skills (next-best-practices, next-cache-components, and next-upgrade) install from reviewed commit b76d687.
Historical use-case-data-patterns provenance: an earlier revision copied Kieran O'Hara's agent at f735349, whose repository did not declare a redistribution licence. The current agent is an original rewrite. Exact evidence and the unresolved older-release permission gap are recorded in its pinned source notes.
Historical test-design-reviewer provenance: an earlier version copied Andrea Laforgia's file at 278e367, whose repository did not declare a redistribution license. The current skill is a fresh rewrite around Dave Farley's public test properties. Exact evidence and the unresolved older-release permission gap are recorded in the skill's pinned source notes.
@dm - Idea credit for the production-parity-skill-builder skill, inspired by the need to keep local, CI, PR, preview, and staging environments aligned with production-only restrictions such as identity-provider group membership.
Tim Ottinger - The story-splitting skill is based on Tim's Splitting Stories - A Resource Listicle and synthesizes the linked work from Tim Ottinger, Bill Wake, Joshua Kerievsky, Gojko Adzic, Neil Killick, George Dinwiddie, Mike Cohn, Richard Lawrence, Peter Green, J. B. Rainsberger, Rachel Davies, and others. Source-by-source provenance is preserved in the skill's resources/source-notes.md.
Paul Bakaus - The impeccable design skills (core skill + 17 steering commands: shape, critique, audit, polish, harden, typeset, colorize, animate, layout, clarify, adapt, bolder, quieter, distill, delight, optimize, overdrive) install from reviewed commit 5d10bc8. Licensed under its pinned Apache 2.0 License. Impeccable builds on Anthropic's original frontend-design skill; see the pinned NOTICE.

📄 License

This repository is open source and available for use. The CLAUDE.md file and agents are designed to be copied and customized for your projects.

⭐ If This Helped You

If you found CLAUDE.md or the agents valuable, consider:

Starring this repo on GitHub
Sharing it with your team
Contributing improvements back
Connecting on LinkedIn to share your experience

The more people who adopt these practices, the better the AI-assisted development ecosystem becomes for everyone.

Name		Name	Last commit message	Last commit date
Latest commit History 352 Commits
.changeset		.changeset
.github/workflows		.github/workflows
.oh-my-zsh/.oh-my-zsh/custom/plugins/zsh-you-should-use		.oh-my-zsh/.oh-my-zsh/custom/plugins/zsh-you-should-use
alacritty		alacritty
claude/.claude		claude/.claude
ghostty/Library/Application Support/com.mitchellh.ghostty		ghostty/Library/Application Support/com.mitchellh.ghostty
gnupg/.gnupg		gnupg/.gnupg
herdr/.config/herdr		herdr/.config/herdr
karabiner/.config/karabiner		karabiner/.config/karabiner
opencode/.config/opencode		opencode/.config/opencode
plans		plans
test		test
tmux		tmux
zellij/.config/zellij		zellij/.config/zellij
zsh		zsh
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
README.md		README.md
SPLIT-CLAUDE-MD-PLAN.md		SPLIT-CLAUDE-MD-PLAN.md
VERSIONING-DISTRIBUTION-ANALYSIS.md		VERSIONING-DISTRIBUTION-ANALYSIS.md
install-claude.sh		install-claude.sh
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml

Folders and files

Latest commit

History

Repository files navigation

Development Guidelines for AI-Assisted Programming

Table of Contents

What This Is

📘 CLAUDE.md: The Development Framework

Core Philosophy

What Makes It Different

Key Sections

📖 Skills Guide

Quick Navigation by Problem

How Skills Work

Scope-to-Implementation Flow

🧪 Testing Principles → skills/testing

🧬 Mutation Testing → skills/mutation-testing

🔷 TypeScript Guidelines → skills/typescript-strict

🔄 Development Workflow (TDD + Refactoring) → skills/tdd + skills/refactoring

🎨 Code Style (Functional Programming) → skills/functional

🤝 Working with Claude → skills/expectations

🔭 Improve Codebase Architecture → skills/improve-codebase-architecture

➖ Reduce System Complexity → skills/reduce-system-complexity

🔎 Evaluate Existing Solutions → skills/evaluate-existing-solutions

🧭 Structure Codebase → skills/structure-codebase

🏗️ Hexagonal Architecture → skills/hexagonal-architecture

📐 Domain-Driven Design → skills/domain-driven-design

📜 Event Sourcing → skills/event-sourcing

🔌 API and Interface Design → skills/api-design

🔐 Secure OAuth and OpenID Connect → skills/secure-oauth-oidc

📕 Working with Legacy Code → skills/finding-seams + skills/characterisation-tests

🔍 Finding Seams → skills/finding-seams

📋 Characterisation Tests → skills/characterisation-tests

🕸️ Graph Engineering → skills/graph-engineering

🔍 Panel Review → skills/panel-review

🎨 Impeccable Design → impeccable.style

Getting Started: Design Context

Building Features: The Craft Flow

Steering Commands: Targeted Improvements

Extracting Reusable Patterns

Recommended Workflow for Frontend Development

Key Concepts

🔥 Grill Me (optional external) → skills.sh/mattpocock/skills/grill-me

🎯 Why These Skills Are Different

Schema-First Decision Framework Example

🤖 Claude Code Agents: Automated Enforcement

1. tdd-guardian - TDD Compliance Enforcer

2. ts-enforcer - TypeScript Strict Mode Enforcer

3. refactor-scan - Refactoring Opportunity Scanner

4. docs-guardian - Documentation Quality Guardian

5. learn - Durable Learning Router

6. progress-guardian - Progress Guardian

7. adr - Architecture Decision Records

8. use-case-data-patterns - Use Case to Data Pattern Analyzer

9. twelve-factor-audit - Twelve-Factor Compliance Auditor

⚡ Slash Commands

Recommended Flow

Optional Project Setup (once per project, with explicit authorization)

Phase 1: Plan the Work (before writing any code)

Phase 3: Implement (repeat fast increments within each slice or PR boundary)

Phase 4: Pre-PR Quality Gate

Phase 5: Continue

Phase 6: Capture Knowledge (throughout and at the end)

🚀 How to Use This in Your Projects

How the Workflow Works (Regardless of Installation Method)

Option 1: Install to ~/.claude/ (Global Personal Config) ⭐ RECOMMENDED

Optional: Enable OpenCode Support

Option 2: Use CLAUDE.md + Agents (Recommended for Projects)

Option 3: Use CLAUDE.md Only - Single File (v1.0.0)

Option 4: Fork and Customize (Advanced)

Architecture generations

📚 Documentation

🎯 Who This Is For

💡 Philosophy

🔄 Continuous Improvement

📦 Personal Dotfiles (The Original Purpose)

Git Aliases

Shell Configuration

Development Tools Configuration

Claude Code Settings

1. `tdd-guardian` - TDD Compliance Enforcer

2. `ts-enforcer` - TypeScript Strict Mode Enforcer

3. `refactor-scan` - Refactoring Opportunity Scanner

4. `docs-guardian` - Documentation Quality Guardian

5. `learn` - Durable Learning Router

6. `progress-guardian` - Progress Guardian

7. `adr` - Architecture Decision Records

8. `use-case-data-patterns` - Use Case to Data Pattern Analyzer

9. `twelve-factor-audit` - Twelve-Factor Compliance Auditor