@avisek_yorkie/cursor-rules 1.0.1 → 1.0.3

package/.cursorrules

@@ -1,16 +1,24 @@
-# Cursor Rules - Generic Tech Stack
+# Cursor Rules - TypeScript/JavaScript
 
-This file contains comprehensive coding rules that apply to any technology stack. These rules are designed to ensure code quality, maintainability, and consistency across all projects.
+Comprehensive rules for **TS/JS** projects: **React**, **Angular**, **Node.js**, **React Native**. Code quality, maintainability, consistency, and AI-assisted development workflow.
 
 ## How to Use These Rules
 
 1. Copy this `.cursorrules` file to your project root
-2. Copy the rule files from the `rules/` folder (code-quality.mdc, documentation.mdc, naming-conventions.mdc) to your project root
+2. Copy the rule files into `.cursor/rules/` (see Rule Categories below)
 3. Cursor will automatically apply these rules when assisting with code
 
 ## Rule Categories
 
-### 1. Code Quality (rules/code-quality.mdc)
+Rules in `.cursor/rules/` are applied automatically.
+
+### 1. AI-Assisted Development (.cursor/rules/ai-assisted-development.mdc)
+- Plan before coding; implement in small, reviewable steps
+- Validate structure first for new features (skeleton then logic)
+- Re-plan when something feels off; don’t refactor legacy out of scope
+- Review checklist: layer, naming, i18n, no hardcoded values, types, a11y
+
+### 2. Code Quality (.cursor/rules/code-quality.mdc)
 - Clean code standards
 - Error handling
 - Security best practices
@@ -18,14 +26,14 @@ This file contains comprehensive coding rules that apply to any technology stack
 - Code complexity management
 - Testing requirements
 
-### 2. Documentation (rules/documentation.mdc)
+### 3. Documentation (.cursor/rules/documentation.mdc)
 - Code documentation standards
 - README requirements
 - API documentation
 - Architecture documentation
 - Inline comments guidelines
 
-### 3. Naming Conventions (rules/naming-conventions.mdc)
+### 4. Naming Conventions (.cursor/rules/naming-conventions.mdc)
 - Variable and function naming
 - Class and type naming
 - File and directory naming
@@ -104,6 +112,9 @@ Before submitting code, ensure:
 
 ## Quick Reference
 
+### AI-Assisted Development (one-line takeaway)
+- **Align on a plan first, then implement in small, reviewable steps**—minimizes rework and keeps code clean and maintainable.
+
 ### Function/Method Guidelines
 - Maximum length: 50 lines (ideally 20-30)
 - Single responsibility
@@ -133,7 +144,7 @@ Before submitting code, ensure:
 
 To use these rules in a specific project:
 
-1. **Copy the rules**: Copy `.cursorrules` and the `.mdc` files from `rules/` to your project root
+1. **Copy the rules**: Copy `.cursorrules` to project root and the `.mdc` files into `.cursor/rules/`
 2. **Customize if needed**: Add project-specific rules while maintaining these core principles
 3. **Team alignment**: Ensure your team is aware of and follows these rules
 4. **Code reviews**: Use the checklists during code reviews
@@ -149,5 +160,5 @@ To use these rules in a specific project:
 
 ---
 
-**Note**: These rules are designed to be generic and applicable to any technology stack. Customize them for your specific project needs while maintaining the core principles.
+**Note**: These rules target TypeScript/JavaScript (React, Angular, Node.js, React Native). Customize for your project while keeping the core principles.
 

package/README.md

@@ -16,18 +16,38 @@ npm install -D @avisek_yorkie/cursor-rules
 npx cursor-rules-init
 ```
 
-This copies `.cursorrules` and the rule files (`code-quality.mdc`, `documentation.mdc`, `naming-conventions.mdc`) into your project root. Cursor will then **use and apply** these rules automatically when you write code, refactor, get completions, or ask for reviews.
+This creates:
+
+- **`.cursorrules`** in your project root  
+- **`.cursor/rules/`** with `code-quality.mdc`, `documentation.mdc`, and `naming-conventions.mdc`
+
+Cursor will **use and apply** these rules automatically when you write code, refactor, get completions, or ask for reviews.
 
 **Manual copy (alternative):**
 
 ```bash
+mkdir -p .cursor/rules
 cp node_modules/@avisek_yorkie/cursor-rules/.cursorrules .
-cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .
+cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .cursor/rules/
 ```
 
-**3. Verify:** Ensure `.cursorrules` and the three `.mdc` files are in your project root. Restart Cursor if needed. You’re done.
+**3. Verify:** Ensure `.cursorrules` exists and `.cursor/rules/` contains the three `.mdc` files. Restart Cursor if needed. You’re done.
+
+**Resulting structure in your project:**
+
+```
+your-project/
+├── .cursorrules
+├── .cursor/
+│   └── rules/
+│       ├── code-quality.mdc
+│       ├── documentation.mdc
+│       └── naming-conventions.mdc
+├── src/
+└── ...
+```
 
-## 📁 Directory Structure
+## 📁 Directory Structure (this package)
 
 ```
 cursor-rules/
@@ -57,14 +77,16 @@ npx cursor-rules-init
 
 **Option B – Manual copy from node_modules:**
 ```bash
+mkdir -p .cursor/rules
 cp node_modules/@avisek_yorkie/cursor-rules/.cursorrules .
-cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .
+cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .cursor/rules/
 ```
 
 **Option C – From a local clone:**
 ```bash
+mkdir -p .cursor/rules
 cp /path/to/cursor-rules/.cursorrules .
-cp /path/to/cursor-rules/rules/*.mdc .
+cp /path/to/cursor-rules/rules/*.mdc .cursor/rules/
 ```
 
 ### Step 3: Verify integration
@@ -79,12 +101,77 @@ Cursor will automatically detect and use the `.cursorrules` file in your project
 
 You can customize these rules for your specific project by:
 - Adding project-specific rules to `.cursorrules`
-- Modifying the `.mdc` files to include team-specific conventions
-- Adding language-specific rules for your tech stack
+- **Adding new `.mdc` files in `.cursor/rules/`** (see below — they are automatically linked and applied)
+- Modifying the existing `.mdc` files to include team-specific conventions
+
+## ➕ Adding Project-Specific Rules (Auto-Applied)
+
+**Yes — any `.mdc` file you add inside `.cursor/rules/` is automatically loaded and applied by Cursor.** You don’t need to “link” it anywhere. Cursor scans the `.cursor/rules/` folder and uses every rule file. **You do not need to add the new file to `.cursorrules`**—it is picked up automatically.
+
+### How to add a project-specific rule
+
+1. Create a new file in your project’s `.cursor/rules/` folder, e.g. `project-conventions.mdc` or `react-patterns.mdc`.
+2. Use the same format as the existing rules: YAML frontmatter + markdown content.
+
+**Example: rule that always applies**
+
+```markdown
+---
+description: Our project's React and API conventions
+alwaysApply: true
+---
+
+# Project Conventions
+
+- Use our design system components from `@company/ui`.
+- API base URL from env: `process.env.VITE_API_URL`.
+- All new screens go under `src/screens/`.
+```
+
+**Example: rule that applies only for certain files**
+
+```markdown
+---
+description: React component patterns for this project
+globs: "**/*.tsx"
+alwaysApply: false
+---
+
+# React Patterns
+
+- Functional components only; use hooks for state.
+- Add testID to interactive elements for E2E.
+```
+
+### Frontmatter options
+
+| Field | Meaning |
+|-------|--------|
+| `alwaysApply: true` | Rule is included in every conversation. |
+| `alwaysApply: false` | Rule is included only when relevant (e.g. when matching files are open). |
+| `globs: "**/*.tsx"` | When set, rule is applied when you work with files matching that pattern. |
+
+### Resulting structure (example)
+
+```
+your-project/
+├── .cursorrules
+├── .cursor/
+│   └── rules/
+│       ├── ai-assisted-development.mdc   # from this package
+│       ├── code-quality.mdc               # from this package
+│       ├── documentation.mdc              # from this package
+│       ├── naming-conventions.mdc         # from this package
+│       └── project-conventions.mdc        # your project-specific rule ✅
+├── src/
+└── ...
+```
+
+Package rules and your own rules work together: Cursor applies all of them. Keep package rules as-is and add project-specific ones in the same folder.
 
 ## 📚 Rule Files Overview
 
-### 1. Code Quality (`rules/code-quality.mdc`)
+### 1. Code Quality (`.cursor/rules/code-quality.mdc`)
 
 Covers:
 - ✅ Clean code standards
@@ -102,7 +189,7 @@ Covers:
 - Never hardcode secrets
 - Keep cyclomatic complexity low
 
-### 2. Documentation (`rules/documentation.mdc`)
+### 2. Documentation (`.cursor/rules/documentation.mdc`)
 
 Covers:
 - ✅ Function/method documentation standards
@@ -119,7 +206,7 @@ Covers:
 - Keep documentation up-to-date
 - Use appropriate documentation tools
 
-### 3. Naming Conventions (`rules/naming-conventions.mdc`)
+### 3. Naming Conventions (`.cursor/rules/naming-conventions.mdc`)
 
 Covers:
 - ✅ Variable and function naming
@@ -137,51 +224,51 @@ Covers:
 - Avoid abbreviations and generic names
 - Use appropriate prefixes for booleans
 
-## 🎯 Usage Examples
+## 📐 Coding Styles & Principles
 
-### Example 1: Starting a New Project
+All rule styles referenced in the code-quality and related rules, in one place.
 
-```bash
-# Create new project
-mkdir my-new-project
-cd my-new-project
+### Core acronyms
 
-# Copy cursor rules
-cp node_modules/@avisek_yorkie/cursor-rules/.cursorrules .
-cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .
+| Style | Full name | Meaning |
+|-------|-----------|----------|
+| **SOLID** | **S**ingle Responsibility, **O**pen/Closed, **L**iskov Substitution, **I**nterface Segregation, **D**ependency Inversion | One thing per class/function; extend without modifying; depend on abstractions. |
+| **DRY** | Don't Repeat Yourself | Extract repeated logic; use configuration over duplication; no copy-paste without refactoring. |
+| **KISS** | Keep It Simple, Stupid | Simple solution > clever; readable > clever; avoid over-engineering. |
+| **YAGNI** | You Aren't Gonna Need It | Build what you need now; don't build for hypotheticals; remove unused code. |
+| **Fail Fast** | — | Validate early at boundaries; fail loudly when something is wrong. |
 
-# Initialize your project (npm, pip, etc.)
-npm init -y  # or your package manager
+### Golden rules (summary)
 
-# Start coding - Cursor will apply the rules automatically!
-```
+1. **Readability > Cleverness** — Code is read 10× more than written  
+2. **Simple > Complex** — Simplest solution that works  
+3. **Small Functions** — One function, one responsibility (~20–30 lines, max 50)  
+4. **Meaningful Names** — Names should reveal intent  
+5. **Handle Errors** — Never fail silently  
+6. **Delete Code** — Remove dead code; don't just comment it out  
+7. **Test Your Code** — If you can't test it, refactor it  
+8. **Composition over Inheritance** — Compose small pieces; avoid deep hierarchies (especially in React)  
+9. **Immutability** — Prefer `const` and immutable updates; avoid hidden mutation  
+10. **Explicit over Implicit** — Clear types and APIs; no magic; avoid `any`  
 
-### Example 2: Adding Rules to Existing Project
+### Additional JS/TS principles
 
-```bash
-# Navigate to your project
-cd /path/to/your/project
+| Principle | One-line meaning |
+|-----------|-------------------|
+| **Pure functions when possible** | Same inputs → same output; no hidden side effects; isolate I/O at boundaries. |
+| **Single source of truth** | One canonical place per piece of state; avoid syncing duplicate state. |
+| **Declarative over imperative** | Describe *what* you want (e.g. JSX) over step-by-step *how*. |
+| **Principle of least surprise** | APIs and behavior should match what a reasonable developer would expect. |
+| **Colocate / locality** | Keep related code together (component + styles + tests; route + handler + types). |
+| **Encapsulation** | Don't leak implementation details; expose a small, stable API surface. |
+| **Strict TypeScript** | Use `strict: true`; avoid `any`; prefer `unknown` and type guards when needed. |
 
-# Copy rules (backup existing .cursorrules if present)
-cp node_modules/@avisek_yorkie/cursor-rules/.cursorrules .
-cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .
+### Documentation & naming (from rule files)
 
-# Review and merge with existing rules if needed
-```
-
-### Example 3: Publishing NPM Package
-
-When publishing an npm package, these rules ensure:
-- ✅ Proper documentation in README
-- ✅ Consistent naming conventions
-- ✅ High code quality
-- ✅ Proper error handling
-- ✅ Security best practices
-
-```bash
-# Your package will follow all rules automatically
-npm publish
-```
+- **Document WHY, not WHAT** — Explain decisions and non-obvious logic.  
+- **Names reveal intent** — Descriptive, specific names from the problem domain; avoid `data`, `info`, `handler`, `manager`.  
+- **Verbs for functions** — e.g. `get`, `set`, `create`, `validate`, `is`, `has`, `can`.  
+- **Boolean prefixes** — `is`, `has`, `can` (e.g. `isActive`, `hasPermission`, `canEdit`).
 
 ## 🔧 Customization Guide
 
@@ -207,7 +294,7 @@ Edit `.cursorrules` to add project-specific rules:
 Edit the appropriate `.mdc` file to add language-specific rules:
 
 ```markdown
-# In rules/code-quality.mdc
+# In .cursor/rules/code-quality.mdc
 
 ### Your Language
 - Follow your language style guide
@@ -273,7 +360,7 @@ Consider versioning your rules:
 ### Rules Not Being Applied
 
 1. Check that `.cursorrules` is in project root
-2. Verify `.mdc` files are in project root (copied from `rules/`)
+2. Verify `.cursor/rules/` contains the three `.mdc` files
 3. Restart Cursor if needed
 4. Check for syntax errors in rule files
 

package/SETUP.md

@@ -18,27 +18,29 @@ npx cursor-rules-init
 
 **Option B – Manual copy:**
 ```bash
+mkdir -p .cursor/rules
 cp node_modules/@avisek_yorkie/cursor-rules/.cursorrules .
-cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .
+cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .cursor/rules/
 ```
 
 **From a local clone:**
 ```bash
-# Copy main file and all rule files to your project root
+mkdir -p .cursor/rules
 cp /path/to/cursor-rules/.cursorrules .
-cp /path/to/cursor-rules/rules/*.mdc .
+cp /path/to/cursor-rules/rules/*.mdc .cursor/rules/
 ```
 
 ### Step 2: Verify files are in place
 ```bash
-ls -la .cursorrules *.mdc
+ls -la .cursorrules .cursor/rules/
 ```
 
 You should see:
-- `.cursorrules`
-- `code-quality.mdc`
-- `documentation.mdc`
-- `naming-conventions.mdc`
+- `.cursorrules` (project root)
+- `.cursor/rules/ai-assisted-development.mdc`
+- `.cursor/rules/code-quality.mdc`
+- `.cursor/rules/documentation.mdc`
+- `.cursor/rules/naming-conventions.mdc`
 
 ### Step 3: Restart Cursor (optional)
 Close and reopen Cursor to ensure rules are loaded.
@@ -46,6 +48,9 @@ Close and reopen Cursor to ensure rules are loaded.
 ### Step 4: Test the rules
 Create a test file and ask Cursor to help you write code. The rules will be automatically applied!
 
+### Step 5: Add project-specific rules (optional)
+Any `.mdc` file you add in `.cursor/rules/` is **automatically linked and applied** by Cursor. Create e.g. `project-conventions.mdc` in that folder with your team’s rules—no extra config needed. See README section **“Adding Project-Specific Rules (Auto-Applied)”** for format and examples.
+
 ## 📦 For NPM Package Publishing
 
 ### Before Publishing Checklist
@@ -102,8 +107,9 @@ If you update the rules (or upgrade the package), sync them to your project:
 
 ```bash
 # From your project root (when using npm package)
+mkdir -p .cursor/rules
 cp node_modules/@avisek_yorkie/cursor-rules/.cursorrules .
-cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .
+cp node_modules/@avisek_yorkie/cursor-rules/rules/*.mdc .cursor/rules/
 ```
 
 ## ✅ Verification

package/bin/init.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * Copies .cursorrules and rules/*.mdc from this package to the current working directory.
+ * Installs Cursor rules: .cursorrules in project root, .mdc files in .cursor/rules/
  * Run from your project root: npx cursor-rules-init
  */
 
@@ -11,13 +11,20 @@ const path = require('path');
 const packageRoot = path.join(__dirname, '..');
 const targetDir = process.cwd();
 
+const cursorRulesDir = path.join(targetDir, '.cursor', 'rules');
+
 const filesToCopy = [
   { src: '.cursorrules', dest: '.cursorrules' },
-  { src: 'rules/code-quality.mdc', dest: 'code-quality.mdc' },
-  { src: 'rules/documentation.mdc', dest: 'documentation.mdc' },
-  { src: 'rules/naming-conventions.mdc', dest: 'naming-conventions.mdc' },
+  { src: 'rules/ai-assisted-development.mdc', dest: '.cursor/rules/ai-assisted-development.mdc' },
+  { src: 'rules/code-quality.mdc', dest: '.cursor/rules/code-quality.mdc' },
+  { src: 'rules/documentation.mdc', dest: '.cursor/rules/documentation.mdc' },
+  { src: 'rules/naming-conventions.mdc', dest: '.cursor/rules/naming-conventions.mdc' },
 ];
 
+if (!fs.existsSync(cursorRulesDir)) {
+  fs.mkdirSync(cursorRulesDir, { recursive: true });
+}
+
 let copied = 0;
 for (const { src, dest } of filesToCopy) {
   const srcPath = path.join(packageRoot, src);
@@ -30,7 +37,10 @@ for (const { src, dest } of filesToCopy) {
 }
 
 if (copied > 0) {
-  console.log('\nCursor rules installed. Cursor will apply them automatically.');
+  console.log('\nCursor rules installed.');
+  console.log('  .cursorrules');
+  console.log('  .cursor/rules/ (ai-assisted-development, code-quality, documentation, naming-conventions)');
+  console.log('\nCursor will apply them automatically.');
 } else {
   console.error('No rule files found. Reinstall @avisek_yorkie/cursor-rules.');
   process.exit(1);

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@avisek_yorkie/cursor-rules",
-  "version": "1.0.1",
-  "description": "Cursor AI rules for code quality, documentation, and naming conventions (JS/TS)",
+  "version": "1.0.3",
+  "description": "Cursor AI rules for TS/JS (React, Angular, Node, React Native): code quality, docs, naming, AI-assisted development.",
   "keywords": [
     "cursor",
     "cursor-rules",
     "code-quality",
     "documentation",
     "naming-conventions",
+    "ai-assisted-development",
     "javascript",
-    "typescript"
+    "typescript",
+    "react",
+    "angular",
+    "node",
+    "react-native"
   ],
   "license": "MIT",
   "repository": {

package/rules/ai-assisted-development.mdc

@@ -0,0 +1,106 @@
+---
+description: AI-assisted development DOs and DON'Ts; plan-first, small steps, review (React, Angular, Node, React Native)
+alwaysApply: true
+---
+
+# AI-Assisted Development: DOs and DON'Ts
+
+This file teaches Cursor **how to think and behave** in your project—not what the code should look like (that’s in code-quality, documentation, naming). So developers can use short, natural prompts and still get high-quality, safe, reviewable code.
+
+Applies to **TypeScript/JavaScript** projects: React, Angular, Node.js, React Native. Align on a plan first, then implement in small, reviewable steps.
+
+---
+
+## DOs
+
+### 1. DO Start with a Plan Before Coding
+- Ask for a **step-by-step approach (to-do list)** before implementation.
+- Clarify: problem, expected outcome, and iterate on the plan until confident.
+- **Planning is cheaper to correct than code.**
+
+### 2. DO Implement in Small, Reviewable Steps
+- Execute the approved plan **one step at a time**.
+- Keep each change **small (~20–30 lines** where possible).
+- Small changes are easier to review, validate, and roll back.
+
+### 3. DO Validate Structure First for New Features
+- For new features, start with the **skeleton** (e.g. empty component in the right folder, route, or API stub).
+- Confirm it matches **codebase patterns and architecture** before adding logic.
+- Avoids costly restructuring later.
+
+**Where "skeleton" lives by stack:**
+
+| Stack        | Skeleton / pattern check                          |
+|-------------|----------------------------------------------------|
+| React       | Component in correct folder; hooks vs components  |
+| Angular     | Module/component in correct module; lazy loading  |
+| Node.js     | Handler/service in correct layer; route/API shape |
+| React Native| Screen/component + testID; native vs JS structure  |
+
+### 4. DO Ask for Code Review After Implementation
+- Once code works end-to-end, ask for review, e.g.:
+  - "Is this good practice in [React/TypeScript/Angular/Node]?"
+  - "Review this against our coding standards and suggest improvements."
+  - "Any performance, accessibility, or maintainability concerns?"
+
+### 5. DO Pause and Re-Plan When Something Feels Off
+- If the output seems wrong or off-track, **stop immediately**.
+- Return to **planning mode**: re-clarify requirements and approach.
+- Do not push forward hoping it will correct itself—early misunderstandings snowball.
+
+---
+
+## DON'Ts
+
+### 1. DON'T Jump Straight into Implementation for Big or Unclear Tasks
+- Skipping planning for complex features or bugs bakes misunderstandings into code.
+- Leads to rework, hard-to-review PRs, and wasted effort.
+
+### 2. DON'T Ask for Massive Changes at Once
+- Large diffs are harder to follow, validate, and debug.
+- Break requests into **smaller, focused tasks**.
+- If you can't easily review what changed, the change is too big.
+
+### 3. DON'T Keep Pushing Forward When Output Seems Wrong
+- If something feels off, do not continue hoping it will self-correct.
+- Each change built on a flawed foundation makes the problem worse.
+- **Stop, assess, and re-plan.**
+
+### 4. DON'T Refactor Legacy Code Just Because AI Suggests It
+- Only fix code **you wrote or made worse**.
+- Do not refactor **working legacy code** to satisfy AI or tool suggestions—you risk breaking stable behavior and scope creep.
+
+### 5. DON'T Blindly Accept AI-Generated Code
+- Always review output for:
+  - **Correct architecture layer** (e.g. component vs service vs API)
+  - **Naming and file organization** (per naming-conventions.mdc)
+  - **i18n** for all user-facing strings (no raw copy in UI)
+  - **No hardcoded values**; use config/env/constants
+  - **Proper TypeScript types** (no `any` unless justified)
+  - **Accessibility**: semantic HTML (web), testID + labels (React Native)
+
+---
+
+## One-Line Takeaway
+
+**Align on a plan first, then implement in small, reviewable steps**—minimizes rework and keeps code clean, predictable, and maintainable.
+
+---
+
+## Behavior for the AI (Cursor)
+
+When the user request is **large or ambiguous**:
+
+1. **Propose a short plan** (bullet to-do list) and ask for confirmation before writing code.
+2. **Keep each response small**: one logical step or ~20–30 lines of change where possible; offer to continue with the next step.
+3. **For new features**: suggest creating the skeleton (file/component/route) first and confirm placement, then add behavior.
+4. **If the user says something is wrong or off**: suggest re-planning or reverting the last step instead of adding more code on top.
+5. **Do not suggest refactors of unrelated legacy code** unless the user explicitly asks or the code is in scope of the current task.
+
+Before suggesting code, do a quick self-check:
+
+- [ ] Right layer (UI / service / API / util)?
+- [ ] Naming and file location match project conventions?
+- [ ] User-facing text ready for i18n (no hardcoded copy)?
+- [ ] No hardcoded config/secrets; types explicit where possible?
+- [ ] Accessibility considered (semantic HTML, testID, labels)?

package/rules/code-quality.mdc

@@ -1,3 +1,8 @@
+---
+description: Code quality standards, error handling, security, and testing
+alwaysApply: true
+---
+
 # Code Quality Standards
 
 These standards apply to the TypeScript/JavaScript ecosystem. Core principles are universal across languages.
@@ -29,6 +34,21 @@ These standards apply to the TypeScript/JavaScript ecosystem. Core principles ar
 - ❌ Don't build for hypothetical future requirements
 - ❌ Remove unused code immediately
 
+### Additional JS/TS Ecosystem Principles
+
+| Principle | Meaning |
+|-----------|--------|
+| **Composition over inheritance** | Prefer composing small modules/hooks over deep class hierarchies. Especially in React: hooks and components over inheritance. |
+| **Immutability** | Prefer `const`; avoid mutating objects/arrays—use spread, `map`/`filter`/`reduce`, immutable updates. Critical for React state and predictability. |
+| **Explicit over implicit** | No magic: clear types (avoid `any`), explicit params and return types, obvious control flow. APIs should be self-evident. |
+| **Pure functions when possible** | Same inputs → same output; no hidden side effects. Makes code testable and predictable. Isolate I/O at boundaries. |
+| **Single source of truth** | One canonical place for each piece of state (e.g. server state, UI state). Avoid syncing duplicate state. |
+| **Declarative over imperative** | Describe *what* you want (e.g. JSX, declarative UI) rather than step-by-step *how*. Prefer `map` over manual loops when it reads better. |
+| **Principle of least surprise** | APIs and behavior should match what a reasonable developer would expect. Naming and signatures should not surprise. |
+| **Colocate / locality** | Keep related code together: component + styles + tests; route + handler + types. Reduces jumping between files. |
+| **Encapsulation** | Don’t leak implementation details from modules/APIs. Expose a small, stable surface; hide the rest. |
+| **Strict TypeScript** | Use `strict: true`; avoid `any`; prefer `unknown` and type guards when type is uncertain. Types are documentation. |
+
 ---
 
 ## Code Structure
@@ -415,3 +435,6 @@ Before submitting code for review, verify:
 8. **Meaningful Names** - Names should reveal intent
 9. **Handle Errors** - Never fail silently
 10. **Delete Code** - Dead code should be removed, not commented out
+11. **Composition over Inheritance** - Compose small pieces; avoid deep hierarchies (especially in React)
+12. **Immutability** - Prefer `const` and immutable updates; avoid hidden mutation
+13. **Explicit over Implicit** - Clear types and APIs; no magic; avoid `any`

package/rules/documentation.mdc

@@ -1,3 +1,8 @@
+---
+description: Documentation standards, README, API docs, and inline comments
+alwaysApply: true
+---
+
 # Documentation Standards - JavaScript/TypeScript
 
 Good documentation is as important as good code. These standards apply to JS/TS projects.

package/rules/naming-conventions.mdc

@@ -1,3 +1,8 @@
+---
+description: Naming conventions for variables, types, files, and APIs
+alwaysApply: true
+---
+
 # Naming Conventions
 
 ## General Naming Principles