fork-discipline
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'.
jezweb · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jezweb/claude-skills --skill 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 | |----------------|-----------
阅读完整来源 ↗