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
  • OpenCode Support
• 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)

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

---

📖 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

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? → preserves facts and voice while fixing substance and sentences

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:

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

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
• — Building on HTTP semantics (RFC 9205): status code discipline, caching, URI schemes, browser security headers

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:

1. Finding seams -- identify places where you can alter behavior without editing at that place, giving you substitution points to isolate code for testing
2. 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:

1. 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.

2. 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

3. Build - Implements the feature following the brief, working through structure → layout → typography → interactive states → edge cases → motion → responsive.

4. 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.

5. 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:

1. Decision frameworks - Concrete questions to answer before taking action (not vague principles)
2. Priority classifications - Objective severity levels to prevent over/under-engineering
3. Anti-pattern catalogs - Side-by-side good/bad examples showing exactly what to avoid
4. Git verification methods - How to audit compliance after the fact
5. Quality gates - Verifiable checklists before commits
6. 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:

1. Does untrusted data cross a runtime boundary? → Validate with a schema
2. Is it exchanged between independently deployed systems? → Validate at ingress/egress
3. Does a production schema already fit a contract-shaped fixture? → Reuse it when useful
4. 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 [email protected] 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, including clarity and simple-english
./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 [email protected] 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 [email protected] 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
  • addyosmani/clarity — co-write, rewrite, review, and deterministic prose diagnostics without inventing facts or voice
  • AminBlg/SimpleEnglish — plain and ASD-STE100-style technical writing for lay, non-native, and translation-oriented readers
  • vercel/next.js — Cache Components optimizer and adoption workflow skills
  • vercel-labs/agent-skills — 72 React/Next.js performance rules and React composition patterns
  • mattpocock/skills — grill-me one-question-at-a-time plan interrogation, and writing-for-agents for documents agents consume
  • anthropics/skills/skill-creator — authoring, evaluating, benchmarking, and description-tuning skills
  • coreyhaines31/marketingskills/seo-audit — technical, on-page, content, and authority SEO audit workflow

Inspecting skills after install:

npx [email protected] list -g              # List installed skills
npx [email protected] 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.

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:

1. 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.

2. Inspection and discovery commands. npx [email protected] 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.

3. 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.

4. 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.

5. 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 [email protected]. 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 [email protected] 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:

• OpenCode Documentation
• OpenCode Rules Configuration
• OpenCode GitHub

---

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:

1. Fork this repository
2. Modify CLAUDE.md to match your team's preferences
3. Customize agents to enforce your specific rules
4. Commit to your fork
5. 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 plus pinned external skills, including clarity, simple-english, web quality, Next.js, React, design, planning, skill-authoring, SEO, Herdr, and Skill Doctor workflows — all installed via skills.sh for multi-agent portability.
• Commands - Slash commands (/setup, /plan, /continue)
• Skill evaluations - promptfoo routing suite that checks each skill fires on the requests it claims and stays quiet on its neighbours'
• 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:

1. AI needs explicit context - Vague principles → inconsistent results. Decision frameworks → reliable outcomes.

2. Quality gates prevent drift - Automated checking catches violations before they become habits.

3. Refactoring needs priority - Not all improvements are equal. Critical/High/Nice/Skip classification prevents over-engineering.

4. Semantic beats structural - Abstract based on meaning (business concepts), not appearance (code structure).

5. Route learning while fresh - Capture evidence while context is available, then put durable knowledge with the source that can keep it true.

6. Explicit "no refactoring" - Saying "code is already clean" prevents the feeling that the refactor step was skipped.

---

🧪 Evaluating the Skills

evals/skills is a promptfoo harness that runs the real Claude Code agent (via the Claude Agent SDK provider) with this bundle mounted and measures two things:

• Routing — 48 realistic developer requests that never name a skill; the assertion is which skill the agent loads (skill-used), which neighbour stays quiet (not-skill-used), and that trivial asks load nothing. This is where a description earns its place.
• Quality — suite-specific fixtures exercise implementation and advisory skills. Deterministic graders read the agent's tool-call trail, workspace, behavior, or written artifact; rubrics are reserved for claims that require judgement. Every case runs with the skills and without, so the gap is what the skill is worth on that case. COVERAGE.md is the authoritative suite list.

cd evals/skills && pnpm install
./run.sh                   # routing, ~10 minutes, uses your Claude Code login
./run-quality.sh tdd       # replace tdd with any suite in COVERAGE.md
pnpm exec promptfoo view   # every transcript and per-metric score

Neither is part of npm test: they spend tokens and sample non-deterministic decisions. The offline guards test/skill-evals-routing.sh and test/skill-evals-quality.sh keep both harnesses wired to real skills and graders. When a case fails, the fix is in the skill — a description line for routing, the body for quality — and the case stays as the regression check. See the suite's README for how to read a failure, add a case, and add a quality suite for another skill.

---

🔄 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)

Personal machine setup is separate from the public skills installer. Use setup-dotfiles.sh for your shell and application configuration; keep using install-claude.sh and its existing options for skills. The personal setup does not install or replace Claude, Codex or OpenCode settings or skills.

macOS (Apple Silicon)

Install Homebrew first, then:

brew install git
git clone https://github.com/citypaul/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./setup-dotfiles.sh
exec zsh

Ubuntu or Debian

sudo apt update
sudo apt install git
git clone https://github.com/citypaul/.dotfiles.git ~/.dotfiles
cd ~/.dotfiles
./setup-dotfiles.sh
exec zsh

The script detects macOS with uname -s and Ubuntu/Debian through /etc/os-release. Other systems are rejected before dependency installation. On Linux, run it as your normal user: it uses sudo for Apt when needed. On Apple Silicon, existing Homebrew packages are not upgraded.

Both paths install Git, GNU Stow, Zsh, tmux, GnuPG/Pinentry, Fzf, Jq, Bat, Python 3 and Zsh autosuggestions/syntax highlighting. Debian/Ubuntu also gets python3-venv. Package installation requires network access and may prompt for your sudo password. Then the script links the configuration and prints exec zsh to start using it. It does not change your login shell automatically.

Existing machines and selected packages

If you already have this checkout, update it instead of cloning again:

cd ~/.dotfiles
git pull --ff-only
./setup-dotfiles.sh
exec zsh

To skip dependency installation or select individual configurations:

# Dependencies already installed; just link the configurations
./setup-dotfiles.sh --skip-deps

# Only configure the shell and tmux
./setup-dotfiles.sh --skip-deps zsh tmux

# List available packages and options
./setup-dotfiles.sh --help

The checkout can live anywhere; links always target your home directory. XDG application configurations honour XDG_CONFIG_HOME (default ~/.config). Keep the checkout in place because the installed files are symlinks into it. Rerunning setup refreshes links without appending settings or completions.

Setup checks every selected package for conflicts before linking any dotfiles. It never overwrites or automatically adopts existing configuration files. If Stow reports a conflict, move the named file to your own backup location and rerun. For example, if .zshrc conflicts:

# -i asks before overwriting an existing backup
mv -i ~/.zshrc ~/.zshrc.before-dotfiles
./setup-dotfiles.sh

A failed preflight may leave empty configuration directories, but does not move or replace your files. Existing links from another checkout also need to be removed or unstowed from that checkout before switching to this one. The older install.sh is retained unchanged for compatibility; use setup-dotfiles.sh for the supported macOS/Linux personal setup.

Included configurations

Package	Configuration
zsh	Shell aliases, completions and optional tool integrations
tmux	Terminal multiplexer configuration
gnupg	Shared GPG preferences, system Pinentry and passphrase caching
alacritty	Terminal appearance and keybindings
zellij	Terminal multiplexer keybindings and theme
ghostty	Shared XDG configuration plus macOS preferences on Macs only
herdr	Terminal workspace manager preferences

All seven packages are selected by default. Application configuration does not install the corresponding desktop application. Install Alacritty, Ghostty, Zellij or Herdr separately when you want to use them; Herdr agent integrations also need their own installation.

Starship, Zoxide, Eza, Node/NVM, pnpm, editors and the development tools referenced by convenience aliases are optional. The shell keeps working without them; ls and cat use the system tools when replacements are unavailable, and Debian/Ubuntu's batcat command is recognised. Project/editor aliases still require their corresponding tools and directories.

An existing Oh My Zsh installation is used, including the vendored zsh-you-should-use plugin at its standard location. Otherwise the shell uses Zsh's native completion and history with the packaged plugins. The setup does not download Oh My Zsh. Machine-specific overrides belong in ~/.zshrc.local.

NVM is loaded lazily from $NVM_DIR/nvm.sh (default ~/.nvm/nvm.sh), with a fallback for existing Homebrew NVM installations. Existing NVM_DIR and PNPM_HOME values are preserved. Shell startup does not create or activate a Python environment: run pyenv-activate explicitly to use ~/pyenv, or use project-specific environments. pyenv-update activates it before upgrading pip.

GnuPG uses the installed system Pinentry instead of a hardcoded Mac executable; new installations keep ~/.gnupg private and separate from the checkout. Ghostty reads shared appearance settings from the XDG location. Its existing macOS configuration location remains for Mac-specific preferences. Back up any conflicting files there too when migrating an existing installation.

Alacritty references Hack Nerd Font and the Night Owl theme at ~/.config/alacritty/themes/themes/night_owl.toml; install those separately for the intended appearance. Its macOS-specific window options do not provide the same decoration behaviour on Linux. Clipboard behaviour should be checked in your terminal/desktop session, particularly on Wayland or over SSH.

Testing personal setup

python3 test/setup-dotfiles.py

This uses temporary homes and a copied checkout with real Stow and Zsh. Package manager calls and optional completion generators are stubbed: it never installs software on your machine. CI runs on macOS Apple Silicon, Ubuntu 24.04 and Debian 13. Every job runs the real dependency installer in a temporary home and repeats the install. After each installation, assertions verify all 12 shared config links (plus the macOS Ghostty override on Macs), their exact source targets, private GnuPG permissions, real runtime directories, and the absence of AI settings. Linux also asserts that no macOS Library directory was created. A shell-startup check verifies Git completion without creating a Python environment. Run the CI workflow manually from GitHub Actions or open a pull request. Graphical applications and live GPG prompts still need a manual check on the target desktop.

---

🤝 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. Matt's grill-me and writing-for-agents skills also install unmodified from reviewed commit 84fdeff.

• Anthropic - The skill-creator skill installs unmodified from reviewed commit , under the shipped inside the skill bundle.

---

📄 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.