The Assignment Model: Rulesets → Projects
In RuleSync: rulesets and projects are separate entities connected by assignments. A ruleset: contains rules (the content). A project: represents a repository (the target). An assignment: connects a ruleset to a project (the mapping). This separation: allows one ruleset to serve many projects (the base ruleset assigned to all 50 projects) and one project to use many rulesets (base + TypeScript + project-specific).
Assignment types: single-ruleset (the simplest — one ruleset per project. Sufficient for small teams with one tech stack), multi-ruleset (multiple rulesets composed into one output file. For organizations with layered rules — base + technology + project), and inherited (projects inherit rulesets from their organization or group. New projects: automatically get the base ruleset). Most organizations: use multi-ruleset with inheritance for the base layer.
The composition order: when a project has multiple rulesets, they are composed in priority order. Default: base (first, lowest priority) → technology (second) → project (last, highest priority). Later rulesets override earlier ones for conflicting rules. The composition: produces a single CLAUDE.md that contains all rules from all assigned rulesets. AI rule: 'The composition order determines which ruleset wins for conflicting rules. Project-specific rules override technology rules, which override base rules.'
Step 1: Assign a Single Ruleset to a Project
From the dashboard: Projects → [your project] → Rulesets → Add Ruleset. Select the ruleset from the dropdown. The assignment: is immediate. The next rulesync pull in that project: downloads the assigned ruleset and generates the output files. For a single-ruleset assignment: the generated CLAUDE.md contains only the rules from that one ruleset.
From the CLI: rulesync assign --project my-app --ruleset organization-base. The command: creates the assignment in the RuleSync dashboard. Verify: rulesync status (shows the assigned rulesets for the current project). Pull: rulesync pull (generates the output files from the assigned ruleset).
When single-ruleset is enough: small teams (under 20 developers) with one main tech stack. The single ruleset: covers all conventions (organization, technology, and project rules in one file). No composition complexity. No inheritance to manage. Simple, effective, and sufficient for most individual projects. AI rule: 'Start with single-ruleset assignment. Add multi-ruleset when the organization grows or when different projects need different technology rules.'
Multi-ruleset composition: powerful for organizations with layered governance. But for a team with one main project and one tech stack: a single ruleset that contains all the rules works perfectly. No composition complexity. No priority ordering. No override resolution. One ruleset, one project, rulesync pull — done. Add multi-ruleset when you need it, not because it exists.
Step 2: Multi-Ruleset Composition
Assign multiple rulesets: Projects → [your project] → Rulesets → Add Ruleset (repeat for each). Set the composition order: drag to reorder (dashboard) or specify priority (CLI: rulesync assign --priority 1 for base, --priority 2 for technology). The composition: merges all assigned rulesets into one output file. Sections from each ruleset: clearly labeled ('## Organization Standards [from: Organization Base v2.4]', '## TypeScript Conventions [from: TypeScript Rules v1.8]').
Conflict resolution: when two rulesets have rules that address the same topic (both define error handling): the higher-priority ruleset wins. The composed output: uses the error handling rule from the technology ruleset (higher priority) over the base ruleset (lower priority). The dashboard: shows conflicts during composition preview (before you pull). You can: resolve the conflict by adjusting one ruleset or accept the override.
Composition preview: before pulling, preview the composed output. Dashboard: Projects → [project] → Preview Composition. CLI: rulesync pull --dry-run. The preview: shows the merged output, highlights overrides (where a higher-priority ruleset replaced a lower-priority rule), and flags potential conflicts. Review the preview before committing the composed output to the repository. AI rule: 'Always preview before the first pull of a new composition. The preview catches: unexpected overrides, missing sections, and composition order issues.'
You assign 3 rulesets to a project: base, TypeScript, and project-specific. The base ruleset says 'Use try-catch for error handling.' The TypeScript ruleset says 'Use the Result pattern.' Without preview: rulesync pull generates a file where both rules exist — confusing the AI. With preview (--dry-run): you see the conflict before the file is generated. Resolution: the TypeScript ruleset (higher priority) overrides the base. Or: update one ruleset to remove the conflict. Preview: 30 seconds. Debugging a conflicting composition: 30 minutes.
Step 3: Inheritance and Bulk Assignment
Inheritance: set a default ruleset for the organization. Settings → Organization → Default Rulesets → Add Ruleset. Every project in the organization: automatically inherits this ruleset. New projects: get the default assignment on creation. No manual assignment needed. The inheritance: ensures every project has at least the base rules, even if the team forgets to assign rulesets manually.
Bulk assignment: for assigning a technology ruleset to many projects at once. Dashboard: Rulesets → [your ruleset] → Bulk Assign. Select multiple projects using filters (technology: TypeScript, tag: frontend). The assignment: applied to all selected projects simultaneously. CLI: rulesync assign --ruleset typescript-rules --projects $(rulesync projects --tag frontend --ids-only). AI rule: 'Bulk assignment: essential at 20+ projects. Without it: assigning a ruleset to 50 projects manually is tedious and error-prone.'
Assignment audit: Dashboard → Organization → Assignment Report. Shows: which projects have which rulesets assigned, which projects are missing expected assignments (e.g., a TypeScript project without the TypeScript ruleset), and which projects have outdated rulesets (assigned version is behind the published version). The report: governance visibility. Use it to ensure: every project has appropriate rulesets, no project is left without rules. AI rule: 'The assignment report: the governance dashboard for rule distribution. Review monthly to ensure complete and current assignments.'
Without inheritance: every new project must be manually assigned rulesets. A developer creates a new repo, forgets to assign rulesets, and starts coding with AI but no rules. The AI: generates generic code. With organization default inheritance: every new project automatically gets the base ruleset. The developer: starts with organizational standards from the first commit. Manual assignment: only needed for technology and project-specific rulesets.
Assignment Summary
Complete RuleSync ruleset assignment guide.
- Model: rulesets and projects are separate. Assignments connect them. One-to-many both directions
- Single-ruleset: one ruleset per project. Simplest. Sufficient for small teams with one tech stack
- Multi-ruleset: base + technology + project composed in priority order. Higher priority overrides lower
- Composition preview: --dry-run or dashboard preview. Check overrides and conflicts before pulling
- Inheritance: organization default rulesets auto-assigned to all projects. No manual step needed
- Bulk assignment: assign one ruleset to many projects at once. Filter by technology or tag
- Assignment audit: monthly report showing coverage, gaps, and outdated assignments
- Scaling: single-ruleset at 1-20 projects. Multi-ruleset at 20-100. Inheritance + bulk at 100+