Fork Discipline

What Is Fork Discipline?

Fork Discipline is a specialized code auditing and enforcement tool designed to maintain a clean separation between core platform code and client-specific customizations in multi-client software projects. In large-scale or SaaS applications, where multiple clients share a common codebase but require unique configurations or features, ensuring a strict boundary between platform (core) and per-client (fork) logic is critical. Fork Discipline automates the detection of code tangling, hardcoded client checks, improper configuration handling, scattered custom code, migration conflicts, and missing extension points. By doing so, it enables teams to keep their codebase maintainable, scalable, and secure.

Why Use Fork Discipline?

As software projects grow to serve multiple clients, technical debt accumulates when client-specific logic seeps into the shared platform code. This "tangling" leads to several issues:

• Increased Maintenance Costs: Fixes or enhancements for one client may inadvertently affect others.
• Difficult Upgrades: Migrations and new features become harder to integrate due to unclear boundaries.
• Risk of Regressions: Unintentional changes to core logic or configurations may break client deployments.
• Reduced Velocity: Developers spend more time tracing dependencies and untangling code instead of delivering value.

By enforcing a clear core/client separation, Fork Discipline preserves the integrity of the shared platform while enabling safe, manageable customization for each client. The tool provides actionable reports and refactoring plans, reducing manual auditing and increasing confidence in the codebase.

How to Get Started

1. Install and Configure Fork Discipline
   Clone or integrate the skill from the repository into your Claude-powered development environment.

2. Project Structure Expectations
   Fork Discipline assumes or encourages the following structure:

   plaintext

   project/
     src/            # CORE: shared, never customized per client
     config/         # DEFAULTS: base config, feature flags, defaults
     clients/
       client1/
         config      # Overrides, merged with defaults
         custom/     # Client-specific features
         schema/     # Migrations, numbered 0100+
         content/    # Templates, seed data, etc.

3. Run the Audit
   Use one of the trigger phrases, such as:

   • "fork discipline"
   • "check the boundary"
   • "platform audit"
   • "refactor for multi-client"

   Fork Discipline will analyze your codebase using static analysis, pattern matching, and configuration comparison.

4. Review Reports and Recommendations
   The tool outputs:

   • A boundary map of core vs. client code
   • Violation report highlighting issues
   • Suggested refactoring steps
   • Optional FORK.md documentation and restructuring scripts

5. Iterate and Enforce
   Apply the refactorings and use the tool regularly to prevent boundary erosion.

Key Features

• Tangled Code Detection
  Identifies instances where platform code is mixed with client-specific logic, such as:

  python

  # BAD: Hardcoded client check in core logic
  if client_id == 'acme_corp':
      enable_special_feature()

  Fork Discipline flags such patterns and suggests moving them to client overrides.

• Config File Analysis
  Detects cases where client configuration files fully replace (instead of extending) base configurations, risking lost defaults or duplicated settings.
  Example:

  yaml

  # BAD: Full replacement
  clients/acme_corp/config.yaml
  # GOOD: Only overrides, merged with base

• Scattered Client Code Discovery
  Finds client-specific files or logic outside the designated clients/ subtree, ensuring all customizations are centralized.

• Migration Conflict Detection
  Locates migration files in client directories that conflict in numbering or logic with the core migrations, preventing deployment errors.

• Extension Point Analysis
  Highlights missing or underused extension points (e.g., plugin hooks, callbacks) in the core platform, guiding developers where to add flexibility.

• Automated Documentation and Scripts
  Generates a FORK.md summarizing the current state of the core/client boundary and, if desired, Bash scripts for automated restructuring.

Best Practices

• Never Modify Core Code per Client
  All client-specific logic should reside in clients/<client>/ directories or be injected via extension points.

• Use Config Merging, Not Replacement
  Client configuration should override only what is necessary, leaving base defaults intact.

• Establish Naming and Migration Conventions
  Use clear, non-conflicting naming for migrations and client files (e.g., numbering client migrations above a threshold).

• Document the Boundary
  Maintain a living FORK.md or similar documentation describing the separation, extension points, and any deviations.

• Continuous Enforcement
  Integrate Fork Discipline into your CI/CD pipeline to catch regressions early.

Important Notes

• Skill Compatibility: Fork Discipline is designed for use with Claude Code and requires access to file system operations (read, write, edit, grep, glob, bash).
• Initial Setup: Projects with legacy tangling may require significant up-front refactoring. Use the provided plans and scripts for a phased approach.
• False Positives: Not all flagged issues are true violations; developer judgment is needed to evaluate context.
• Team Adoption: Success depends on team buy-in. Educate all contributors about the principles and mechanics of the core/client boundary.
• Security Considerations: Strict boundaries not only ease maintenance, but also help enforce security and data isolation between clients.

By systematically auditing and enforcing the boundaries in multi-client projects, Fork Discipline makes large-scale software more maintainable, robust, and ready for growth.