Zero-Effort Rule Freshness
The manual workflow: developer runs npm install (installs dependencies), then separately runs rulesync pull (updates AI rules). The problem: developers forget the second step. Rules become stale. AI generates code with old conventions. The postinstall solution: add rulesync pull to the npm postinstall hook. Every npm install: automatically pulls the latest rules. The developer: never thinks about rule freshness. It happens automatically with every dependency install.
When postinstall triggers: after npm install (installing all dependencies), after npm ci (CI-style install), after pnpm install, and after yarn install. All package managers: run the postinstall hook. The RuleSync pull: runs silently after dependencies are installed. The developer: sees the updated CLAUDE.md and .cursorrules in their working directory. If the rules changed: the files are updated. If they are current: the pull is a no-op (fast, no file changes).
The trade-off: postinstall adds 2-3 seconds to every npm install. For most projects: npm install takes 10-30 seconds. The 2-3 second addition: barely noticeable. The benefit: rules are always current. The trade-off: overwhelmingly positive for teams where developers forget to run rulesync pull manually.
Step 1: Configure the Postinstall Hook (1 Minute)
Add to package.json scripts: 'postinstall': 'rulesync pull || true'. The || true: ensures the postinstall hook does not fail if rulesync pull encounters an error (network issue, API key not configured, RuleSync service temporarily unavailable). Without || true: a RuleSync error would cause npm install to fail â blocking the developer from installing any dependencies. With || true: the pull is best-effort. If it succeeds: rules updated. If it fails: rules stay at the previous version, and the developer can investigate later.
For teams that want stricter enforcement: remove the || true. 'postinstall': 'rulesync pull'. Now: if the pull fails (outdated API key, network error): npm install fails. The developer: must fix the RuleSync issue before they can install dependencies. This is appropriate for: organizations where current rules are a hard requirement and a failed pull should block development. AI rule: '|| true for most teams (graceful failure). Remove || true for strict enforcement (block on failure). The choice: depends on how critical rule freshness is to the organization.'
First-time setup: developers who have never used RuleSync: do not have the CLI installed or an API key configured. The postinstall hook: fails (rulesync command not found). With || true: the failure is silent. The developer: installs dependencies normally. They set up RuleSync later when onboarded. Without || true: npm install fails for anyone without RuleSync configured. AI rule: 'With || true: the postinstall hook is opt-in. Developers without RuleSync: unaffected. Developers with RuleSync: get automatic rule updates. Everyone can install dependencies.'
Without || true: a developer who has not configured RuleSync runs npm install. The postinstall fails: 'rulesync: command not found.' npm install: fails. The developer: confused and frustrated. Cannot install dependencies until they figure out RuleSync. With || true: the postinstall fails silently. npm install: succeeds. The developer: installs dependencies normally. They configure RuleSync later during onboarding. || true: makes the hook opt-in rather than mandatory.
Step 2: Advanced Postinstall Configuration
Conditional pull: only pull if the RuleSync CLI is installed. 'postinstall': 'which rulesync > /dev/null 2>&1 && rulesync pull || true'. The which command: checks if rulesync is available. If yes: pulls rules. If no: skips silently. This: more explicit than || true for handling the 'CLI not installed' case. The developer without RuleSync: sees no error, no warning, no confusion.
Environment-aware: only pull in development, not in CI (where rulesync pull --check is used instead). 'postinstall': 'if [ -z "$CI" ]; then rulesync pull || true; fi'. The $CI variable: set by most CI platforms (GitHub Actions, GitLab CI, CircleCI). In CI: the postinstall skips the pull (CI uses --check instead). Locally: the postinstall pulls rules. This separation: keeps CI behavior controlled (--check for verification) while giving developers automatic freshness (pull for convenience).
Suppress output: 'postinstall': 'rulesync pull --quiet || true'. The --quiet flag: suppresses the success message ('Rules updated to v2.4.0'). The developer: sees a clean npm install output. If the rules were updated: the files change silently. If the developer needs to see the update: run rulesync status for current version information. AI rule: 'The --quiet flag keeps npm install output clean. Without it: every npm install shows a RuleSync message that most developers will ignore. Quiet: cleaner. Verbose: only when debugging.'
npm install: 15 seconds for dependencies. Postinstall rulesync pull: 2-3 additional seconds. Total: 17-18 seconds. The 2-3 seconds: barely noticeable. The benefit: every developer's AI rules are current after every npm install. No separate rulesync pull step to remember. No stale rules. No AI generating code with old conventions. The 2-3 second investment: returns hours of prevented inconsistency over the project's lifetime.
Step 3: Rolling Out Postinstall to the Team
Add the postinstall hook to package.json and commit. Every developer who runs npm install: now gets automatic rule pulls. No per-developer configuration needed. The commitment: appears as a one-line change in a PR. Review: the team should know that npm install now pulls AI rules automatically. Communication: announce in Slack or the team standup: 'npm install now automatically updates your AI rules. No action needed from you.'
New developer onboarding: the new developer clones the repo, runs npm install, and gets: all dependencies installed AND the latest AI rules pulled. If they have RuleSync configured (API key set): rules are current from the first install. If they have not configured RuleSync yet: the postinstall silently skips (with || true). When they configure RuleSync later: the next npm install pulls the rules. AI rule: 'Postinstall simplifies onboarding. The new developer does not need to know about rulesync pull. It happens automatically. When they learn about RuleSync: the rules are already there.'
Handling rule file changes: after the postinstall updates the rule files, the developer may have uncommitted changes to CLAUDE.md or .cursorrules. Git status: shows the modified files. The developer: can commit the updated rules alongside their feature changes, or separately. Recommendation: commit rule updates separately (a clean commit message: 'chore: update AI rules to v2.5.0'). AI rule: 'Rule updates from postinstall: should be committed. Do not .gitignore the generated files â other developers need them. Commit separately or with the next feature commit.'
The postinstall generates CLAUDE.md and .cursorrules. A developer thinks: 'These are generated files. I should .gitignore them.' No: the generated files must be committed to git. Why? Developers who do not have RuleSync CLI installed: still need the rule files. AI tools read the files from the repo, not from RuleSync. The CLI is the delivery mechanism. The committed files are the product. If you .gitignore them: developers without the CLI have no rules.
Postinstall Summary
Complete RuleSync postinstall setup.
- Script: 'postinstall': 'rulesync pull || true' in package.json. One line. Done
- Triggers: npm install, npm ci, pnpm install, yarn install. All package managers supported
- || true: graceful failure. RuleSync not installed or unavailable: npm install still works
- Strict mode: remove || true to block npm install on RuleSync failure
- Conditional: check for CLI with 'which rulesync', skip in CI with $CI check
- Quiet: --quiet flag suppresses output. Cleaner npm install logs
- Onboarding: new developer runs npm install â rules pulled automatically. Zero extra steps
- Commit: rule file updates should be committed to git. Separate commit recommended