DOCSEARCHbyAlgolia
Submit Docs

citypaul/.dotfiles

repository·main·Indexed 20 days ago

https://github.com/citypaul/.dotfiles

A development framework for AI-assisted programming targeting Claude Code and OpenCode. It centers around a CLAUDE.md file providing guidelines, specialized agents for TDD, TypeScript strict mode, and functional programming. The repository includes automated quality skills, slash commands, and a structured scope-to-implementation flow covering testing, architecture, and UI/UX design via the impeccable pipeline.

Tokens
27.5K
Snippets
54
Records
87
Agent score
72%

What's inside citypaul/.dotfiles

  1. Overview of the CLAUDE.md development framework

    main

    The claude/ directory contains a framework for AI-assisted programming. It is designed to provide explicit context and decision frameworks to AI agents (like Claude Code) to ensure consistent quality and prevent architectural drift.

    Core Components:

    • CLAUDE.md: Core development principles and decision frameworks.
    • Skills: Auto-discovered patterns and quality standards (e.g., web-quality, next-skills, impeccable, seo-audit) installed via skills.sh.
    • Commands: Slash commands for common tasks like /setup, /pr, /plan, /continue, and /generate-pr-review.
    • Agents: Individual agent configurations (e.g., tdd-guardian, ts-enforcer, refactor-scan, docs-guardian) that enforce specific quality gates.
    • Agents README: Detailed documentation and examples for using these agents.

  2. Overview of the AI-Assisted Development Framework

    main

    This repository provides a comprehensive development framework for AI-assisted programming. It is centered around a CLAUDE.md file that contains development guidelines, specialized agents for Test-Driven Development (TDD), TypeScript strict mode, and functional programming, as well as a collection of automated quality skills and slash commands.

    While the repository also contains personal dotfiles (shell configurations, git aliases, etc.), its primary utility for developers is the AI development guidance designed to work with tools like Claude Code and OpenCode.

  3. Understand the CLAUDE.md Development Framework

    main
    CLAUDE.md is a living document that defines development principles, patterns, and anti-patterns for AI-assisted programming. It moves beyond simple style guides by providing decision frameworks, priority classifications (Critical/High/Nice/Skip), quality gates (verifiable checklists), and anti-pattern catalogs. It is designed to transform abstract concepts into actionable decision frameworks for developers and AI agents.

  4. What is the Impeccable frontend design system?

    main

    Impeccable is a comprehensive frontend design vocabulary and quality system designed to guide AI coding tools toward high-quality, distinctive interfaces. It builds upon Anthropic's frontend-design skill but provides a much deeper methodology, including a systematic font selection process, the OKLCH color model, modular spacing systems, and a structured 'AI Slop Test' to detect and avoid generic AI aesthetics. It operates through three primary modes:

    • Craft: A full build flow (shape $\rightarrow$ build $\rightarrow$ iterate).
    • Teach: Learning the design system.
    • Extract: Pulling reusable design tokens.

    The system consists of one core skill, 18 steering commands, and 12 reference files.

  5. Design deep modules with low caller burden

    main

    A module is considered 'deep' when it provides a cohesive capability per unit of caller burden. Instead of creating shallow pass-through layers, a deep module should hide its internal complexity (policy, sequencing, representation, and recovery) behind a stable public contract.

    Module Design Principles

    • Full Interface Burden: A module must define its operations, types, invariants, lifecycle, effects, errors, configuration, ordering, and performance expectations.
    • Leverage and Locality: Concentrate related knowledge, changes, and verification within a single owner so callers coordinate less.
    • Behavior-preserving Inlining Test: A module is useful only if its behavior cannot simply be removed via inlining without changing the system's outcome.
    • Safe Deepening: When increasing module depth, characterize behavior and strengthen mutation detection before redirecting callers incrementally.

  6. Modularize CLAUDE.md for better context management

    main

    To prevent excessive context usage in Claude Code sessions, avoid maintaining a single massive CLAUDE.md file. Instead, implement a hierarchical structure:

    1. Main CLAUDE.md: Keep this file small (~300 lines). It should contain:
      • Core Philosophy: Non-negotiable high-level principles.
      • Quick Reference: The most frequently used checklists or rules.
      • Section Summaries: Brief descriptions of topics followed by @import statements to detailed files.
    2. Detailed docs/ directory: Move exhaustive details, large code examples, and specific guidelines into dedicated files (e.g., testing.md, typescript.md, workflow.md).

    This approach ensures Claude only loads heavy, detailed context when specifically working on a relevant topic, while always having access to the core principles.

  7. Core Concepts: Context, Slop, and Bans

    main

    Context Gathering Protocol

    Every design skill checks for project context before proceeding. It looks for a Design Context section in loaded instructions or a .impeccable.md file in the project root. If neither is found, it forces /impeccable teach to prevent generic output.

    AI Slop Test

    A structured checklist used during the craft flow to detect and fight generic AI aesthetics, such as:

    • Purple-to-blue gradients
    • Inter/Roboto font defaults
    • Glassmorphism
    • Bounce/elastic easing
    • Dark mode with neon accents
    • Side-stripe borders
    • Gradient text

    Absolute Bans

    The framework treats the following CSS patterns as hard failures:

    • Side-stripe borders: border-left or border-right > 1px on cards/callouts.
    • Gradient text: Using background-clip: text with gradients.

  8. Apply Behavior-Driven Testing Principles

    main

    To prevent tests from breaking during refactoring, focus on behavior rather than implementation. Avoid testing internal function calls or private structures; instead, test the observable outcomes of the system.

    Key Principles:

    • Use factory function patterns for test data (avoid let or beforeEach).
    • Aim for 100% coverage through business behavior rather than line coverage.
    • Validate test data using shared schemas.
    • A single file (e.g., payment-processor.ts) can achieve 100% coverage through its consumer's behavior tests without needing a 1:1 test file mapping.
    // ❌ BAD - Implementation-focused test (breaks on refactor)
// This fails if you rename or restructure the internal 'validateAmount' function.
it("should call validateAmount", () => {
  const spy = jest.spyOn(validator, 'validateAmount');
  processPayment(payment);
  expect(spy).toHaveBeenCalled();
});

// ✅ GOOD - Behavior-focused test (refactor-safe)
// This passes as long as the business rule (rejecting negative amounts) remains true.
it("should reject payments with negative amounts", () => {
  const payment = getMockPayment({ amount: -100 });
  const result = processPayment(payment);
  expect(result.success).toBe(false);
  expect(result.error.message).toBe("Invalid amount");
});

  9. Core Philosophy of the Development Framework

    main

    The framework is built on several non-negotiable principles:

    • TDD is non-negotiable for behavior change: Use fast RED-GREEN-REFACTOR increments. Mutation testing or alternate evidence is applied only at the end-of-phase PR-readiness gate.
    • Behavior over implementation: Tests must verify what code does, not how it is implemented.
    • Immutability by default: Prioritize pure functions and immutable data structures.
    • Schema-first with nuance: Use runtime validation at trust boundaries and types for internal logic.
    • Semantic refactoring: Abstract code based on its meaning rather than its structural shape.
    • Reuse before invention: Check local/platform capabilities and established solutions before building bespoke machinery.
    • Explicit documentation: Capture learnings immediately while context is fresh.

  10. Best practices for maintaining modular CLAUDE.md files

    main

    When developing or maintaining a modular CLAUDE.md structure, follow these rules:

    • Declarative Imports: Use the @path/to/file.md syntax for imports. Do not use prose to describe imports.
    • Inline Core Principles: The philosophy section must always be immediately visible in the main file.
    • Preserve Detail: Do not summarize content; all examples and technical details must be preserved in the imported files.
    • Frequent Testing: Use the /memory command during development to verify how the AI agent perceives the structure.
    • Continuous Documentation: Update the implementation plan immediately if the structure changes.

  11. Capture knowledge with specialized agents

    main

    Throughout the development lifecycle, use specialized agents to document knowledge and prevent regression:

    • learn agent: Captures gotchas and patterns into .claude/CLAUDE.md.
    • adr agent: Documents significant architectural decisions.
    • docs-guardian agent: Updates user-facing documentation.

  12. Use Mutation Testing to Verify Test Effectiveness

    main

    Code coverage only measures which lines are executed. Mutation testing measures if your tests actually detect changes to the logic. It works by injecting 'mutants' (small logic changes) into your code and checking if your tests fail.

    Best Practices:

    • Use a Stryker-first workflow for incremental or full-project runs.
    • Run mutation testing as a single end-of-phase PR-readiness gate rather than after every TDD increment.
    • Avoid identity values in tests (e.g., 0 for addition/subtraction, 1 for multiplication/division, empty arrays, or all true/false). Identity values allow mutants to survive because the result of the mutation is identical to the original code.

    Survivor Triage: Fix obvious gaps immediately; seek human judgment for subtle domain-specific survivors.

    // Production code
const calculateTotal = (price: number, quantity: number): number => {
  return price * quantity;
};

// Mutant: price / quantity

// ❌ WEAK TEST - Would NOT catch mutant because 10 * 1 === 10 / 1
it('calculates total', () => {
  expect(calculateTotal(10, 1)).toBe(10);
});

// ✅ STRONG TEST - Would catch mutant because 10 * 3 !== 10 / 3
it('calculates total', () => {
  expect(calculateTotal(10, 3)).toBe(30);
});