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.

Table of Contents

• What This Is
• CLAUDE.md: The Development Framework
• Claude Code Agents: Automated Enforcement
• Slash Commands
• How to Use This in Your Projects

• Working with Legacy Code
• Documentation
• Who This Is For
• Philosophy
• Evaluating the Skills
• Continuous Improvement
• Personal Dotfiles
• Contributing
• Contact

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:

1. 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 and clarity from Addy Osmani + simple-english from Amin Boulegroun + 2 Next.js Cache Components skills from vercel/next.js + 2 React skills from vercel-labs/agent-skills + the optional grill-me planning interview and writing-for-agents skills from mattpocock/skills + skill-creator from anthropics/skills + the seo-audit marketing skill from coreyhaines31/marketingskills + Skill Doctor from Warp, and automated quality guidance (what most visitors want)
2. Personal dotfiles - My shell configs, git aliases, and tool configurations (what this repo was originally for)

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 (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 | | XState | Front-end flow logic as XState v5 statecharts and actors. Fires on ordinary React code that hand-rolls a statechart — a submitting/isLoading useState, a promise chain setting state in sequence, a double-submit guard, an error cleared before a retry — because under-modelling, not over-modelling, is how agents actually fail. Classifies state by what changes it rather than what it renders, defers to the repository's own rule for which layer owns machines, and regenerates a Mermaid stateDiagram-v2 render whenever a machine is designed or changed. 6 deep-dive references | → skills/xstate | | React Performance | Measure-first method for React and Next.js performance: baseline the symptom, attribute the cost with evidence, apply one rule per diff from the pinned Vercel catalogues, then re-measure and revert what does not move the number. Owns the routing across the overlapping perf skills and the reconciliation where general performance advice would trade away behaviour tests, immutability, or type safety | → skills/react-performance | | Render Code Shape | Read-only render of how code composes — entry points, frame edge, module boundaries, the types crossing them, signatures, and a cited call graph per wiring, with [NEW] for work not yet built. Every name and path is read from source and cited; only bodies are pseudo. Adapted from Adam Bulmer's pseudocode skill with source notes | → skills/render-code-shape | | 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 [email protected] 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 | | Writing for Agents | Writing documents an agent consumes — a SKILL.md, CLAUDE.md/AGENTS.md, a doc behind a pointer. Context pointers and trigger wording, the context/cognitive load split, the information hierarchy and progressive disclosure, and completion criteria that resist premature completion. Routes by audience: technical-writing owns human-facing prose | → mattpocock/skills/writing-for-agents | | Clarity | Co-writes, rewrites, reviews, or diagnoses reader-facing prose at sentence level while preserving facts, attribution, medium, and the author's voice | → addyosmani/clarity | | Simple English | Writes plain technical prose for lay and non-native readers; explicit STE requests add ASD-STE100 vocabulary discipline | → AminBlg/SimpleEnglish | | Skill Creator | Anthropic's own skill-authoring loop: draft, write test prompts, run evals, review results qualitatively and quantitatively, rewrite, and tune the description for trigger accuracy | → anthropics/skills/skill-creator | | Skill Doctor | Scores recent local agent conversations for efficiency, code quality, and skill coverage, then drafts evidence-backed skill edits and a shareable local report. Supports Claude Code, Codex, and Warp without uploading transcripts | → Warp Skill Doctor | | Next.js Skills | Cache Components optimization and adoption workflows, version-matched with the framework | → vercel/next.js skills | | React Best Practices | Vercel Engineering's 72 impact-ordered React/Next.js performance rules — waterfalls and bundle size first, micro-optimizations last. The rule catalogue behind the first-party react-performance method | → agent-skills | | Composition Patterns | Compound components, avoiding boolean-prop proliferation, context providers, and React 19 API changes (ref as a prop, no forwardRef) | → agent-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 | vercel/next.js skills | Cache Components optimizer and adoption workflows (best-practice and upgrade knowledge now ships inside Next.js itself) | | React or Next.js feels slow | react-performance | Baseline, attribute the cost, then apply one rule per diff from the pinned Vercel catalogue and re-measure | | Writing front-end flow logic, or about to add a submitting/isLoading flag | xstate | Classify by what changes the state, not what it renders; a hand-rolled statechart is the failure this catches | | Need to understand how an unfamiliar path composes, or pseudocode a change first | render-code-shape | Read-only cited call graph, module boundaries, and the types crossing them | | 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 | | Reader-facing prose feels generic, hollow, or AI-shaped | clarity | Preserve truth and voice; fix substance before surface patterns | | Technical prose must be plain, translatable, or ASD-STE100-style | simple-english | Short active sentences, one meaning per term, condition before command | | 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
• Rewriting important prose that feels generic or AI-shaped? → clarity preserves facts and voice while fixing substance and sentences
• Writing for lay, non-native, or STE-governed readers? → simple-english applies plain or strict Simplified Technical English
• 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

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

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

Ask these in order:

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

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

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

⚠️ **High Value (Fix T

... (README truncated for length)