/fork-discipline

name: fork-discipline
description: "Audit and enforce the core/client boundary in multi-client projects. Detects where shared platform code is tangled with client-specific code, finds hardcoded client checks, config files that replace instead of merge, scattered client code, migration conflicts, and missing extension points. Produces a boundary map, violation report, and refactoring plan. Optionally generates FORK.md documentation and restructuring scripts. Triggers: 'fork discipline', 'check the boundary', 'is this core or client', 'platform audit', 'client separation', 'fork test', 'refactor for multi-client', 'clean up the fork'."
compatibility: claude-code-only
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash

Fork Discipline

Audit the core/client boundary in multi-client codebases. Every multi-client project should have a clean separation between shared platform code (core) and per-deployment code (client). This skill finds where that boundary is blurred and shows you how to fix it.

The Principle

project/
  src/            ← CORE: shared platform code. Never modified per client.
  config/         ← DEFAULTS: base config, feature flags, sensible defaults.
  clients/
    client-name/  ← CLIENT: everything that varies per deployment.
      config      ← overrides merged over defaults
      content     ← seed data, KB articles, templates
      schema      ← domain tables, migrations (numbered 0100+)
      custom/     ← bespoke features (routes, pages, tools)

**The fork test**: Before modifying any file, ask "is this core or client?" If you can't tell, the boundary isn't clean enough.

When to Use

• Before adding a second or third client to an existing project
• After a project has grown organically and the boundaries are fuzzy
• When you notice `if (client === 'acme')` checks creeping into shared code
• Before a major refactor to understand what's actually shared vs specific
• When onboarding a new developer who needs to understand the architecture
• Periodic health check on multi-client projects

Modes

| Mode | Trigger | What it produces | |------|---------|-----------------| | **audit** | "fork discipline", "check the boundary" | Boundary map + violation report | | **document** | "write FORK.md", "document the boundary" | FORK.md file for the project | | **refactor** | "clean up the fork", "enforce the boundary" | Refactoring plan + migration scripts |

Default: **audit**

---

Audit Mode

Step 1: Detect Project Type

Determine if this is a multi-client project and what pattern it uses:

| Signal | Pattern | |--------|---------| | `clients/` or `tenants/` directory | Explicit multi-client | | Multiple config files with client names | Config-driven multi-client | | `packages/` with shared + per-client packages | Monorepo multi-client | | Environment variables like `CLIENT_NAME` or `TENANT_ID` | Runtime multi-client | | Only one deployment, no client dirs | Single-client (may be heading multi-client) |

If single-client: check if the project CLAUDE.md or codebase suggests it will become multi-client. If so, audit for readiness. If genuinely single-client forever, this skill isn't needed.

Step 2: Map the Boundary

Build a boundary map by scanning the codebase:

CORE (shared by all clients):
  src/server/          → API routes, middleware, auth
  src/client/          → React components, hooks, pages
  src/db/schema.ts     → Shared database schema
  migrations/0001-0050 → Core migrations

CLIENT (per-deployment):
  clients/acme/config.ts    → Client overrides
  clients/acme/kb/          → Knowledge base articles
  clients/acme/seed.sql     → Seed data
  migrations/0100+          → Client schema extensions

BLURRED (needs attention):
  src/server/routes/acme-custom.ts  → Client code in core!
  src/config/defaults.ts line 47    → Hardcoded client domain

Step 3: Find Violations

Scan for these specific anti-patterns:

Client Names in Core Code

# Search for hardcoded client identifiers in shared code
grep -rn "acme\|smith\|client_name_here" src/ --include="*.ts" --include="*.tsx"

# Search for client-specific conditionals
grep -rn "if.*client.*===\|switch.*client\|case.*['\"]acme" src/ --include="*.ts" --include="*.tsx"

# Search for environment-based client checks in shared code
grep -rn "CLIENT_NAME\|TENANT_ID\|process.env.*CLIENT" src/ --include="*.ts" --include="*.tsx"

**Severity**: High. Every hardcoded client check in core code means the next client requires modifying shared code.

Config Replacement Instead of Merge

Check if client configs replace entire files or merge over defaults:

// BAD — client config is a complete replacement
// clients/acme/config.ts
export default {
  theme: { primary: '#1E40AF' },
  features: { emailOutbox: true },
  // Missing all other defaults — they're lost
}

// GOOD — client config is a delta merged over defaults
// clients/acme/config.ts
export default {
  theme: { primary: '#1E40AF' },  // Only overrides what's different
}
// config/defaults.ts has everything else

Look for: client config files that are suspiciously large (close to the size of the defaults file), or client configs that define fields the defaults already handle.

**Severity**: Medium. Stale client configs miss new defaults and features.

Scattered Client Code

Check if client-specific code lives outside the client directory:

# Files with client names in their path but inside src/
find src/ -name "*acme*" -o -name "*smith*" -o -name "*client-name*"

# Routes or pages that serve a single client
grep -rn "// only for\|// acme only\|// client-specific" src/ --include="*.ts" --include="*.tsx"

**Severity**: High. Client code in `src/` means core is not truly shared.

Missing Extension Points

Check if core has mechanisms for client customisation without modification:

| Extension point | How to check | What it enables | |----------------|-----------