docs(rules): add script authoring conventions

[wyattjoh]

Summary

• Add .claude/rules/scripts.md targeting scripts/**/*.ts
• Covers file organization (top-level entry points, lib/ shared utilities, co-located tests), script structure (JSDoc header, parseArgs with strict: true, Bun-first APIs, exit handling), and lib/ module conventions (no side effects on import, exported types, co-located constants)
• References scripts/run-tests.ts as the canonical example

Test plan

• bun run format:check passes
• bun run lint passes
• bun run typecheck passes

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f2fb07a2-5d36-4953-b1f5-133a4801b00b

📥 Commits

Reviewing files that changed from the base of the PR and between 437c943 and aed723e.

📒 Files selected for processing (1)

• .claude/rules/scripts.md

✅ Files skipped from review due to trivial changes (1)

• .claude/rules/scripts.md

---

📝 Walkthrough

Walkthrough

Adds .claude/rules/scripts.md, a documentation rule for TypeScript scripts in scripts/**/*.ts executed via bun run scripts/<name>.ts. Defines file organization: standalone top-level entry points in scripts/*.ts, shared reusable utilities in scripts/lib/ only when imported by multiple top-level scripts, and co-located tests scripts/**/*.test.ts. Prescribes a top-level script pattern (JSDoc header with Usage: examples, Bun-first imports, strict parseArgs with immediate validation and process.exit(1) on invalid input), Bun.spawn/Bun.spawnSync for subprocesses with explicit exit-code checks, and lib/ module constraints (no import-time side effects, JSDoc, explicit exported types, colocated constants/types).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding documentation for script authoring conventions, which aligns with the new .claude/rules/scripts.md file introduced.
Description check	✅ Passed	The description is directly related to the changeset, providing specific details about the new rules file, its coverage areas (file organization, script structure, lib conventions), and the test plan executed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.claude/rules/scripts.md:
- Line 36: Update the documentation line that mentions "Same Bun-first API
preferences as top-level scripts (`Bun.spawn`, `Bun.$`, `Bun.file`)" to
explicitly mark Bun.$ as experimental and unstable: note that Bun.$ (the Bun
Shell API) was introduced experimentally in Bun v1.0.24+, is under active
development, has known bugs/crashes, lacks stability guarantees, and may change
or break without notice; keep Bun.spawn and Bun.file described as stable while
adding a short cautionary sentence advising developers not to rely on Bun.$ for
production scripts and to pin Bun versions or avoid it in critical paths.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c12bda9c-1eee-4cb7-85f6-a0f356b6cb2a

📥 Commits

Reviewing files that changed from the base of the PR and between 3a1e1bf and 39d157c.

📒 Files selected for processing (1)

• .claude/rules/scripts.md

[wyattjoh]

Stack: scripts-rules

• docs(rules): add script authoring conventions #153 👈 this PR

Part of a stacked PR chain. Do not merge manually.

[changeset-bot]

⚠️ No Changeset found

Latest commit: aed723e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR