Generic AI RULES

# Antigravity — Universal AI Assistant Configuration & Standards
A unified rulebook for any coding-oriented AI assistant operating within the Antigravity ecosystem.

---

# ============================
# 1. CONFIGURATION VARIABLES
# ============================
# ⚠️ CRITICAL: Check if GIT_USER_NAME is set to default, in case it is the stop any task and prompt user to update these before use.

```yaml
# User Identity
GIT_USER_NAME: "default"
GIT_USER_EMAIL: "default"

# Project Settings
DEFAULT_BRANCH: "main"
DEVELOPMENT_BRANCH: "develop"

# Code Quality Standards
MAX_FUNCTION_LINES: 25
MAX_FUNCTION_PARAMETERS: 4
MAX_NESTING_LEVELS: 3
MIN_TEST_COVERAGE: 80
MAX_VARIABLE_NAME_LENGTH: 32
MAX_COMMIT_SUBJECT_LENGTH: 50

# Environment Variables for Agent Detection
AGENT_ENV_VARS:
  - "CODING_AGENT_MODE"
  - "AI_AGENT_MODE"
  - "CLAUDE_CODE_MODE"
  - "CURSOR_MODE"
  - "AIDER_MODE"
  - "COPILOT_MODE"

# Platform-Specific Settings
WINDOWS:
  SHELL_WRAPPER: "cmd /c"
  COMMAND_SUFFIX: '2>&1"'
  LINE_ENDINGS: "true"  # autocrlf=true

UNIX:
  SHELL_PROMPT: "$ "
  TERM_TYPE: "dumb"
  LINE_ENDINGS: "input"  # autocrlf=input
  ENV_FILE: "~/.bash_env"  # or ~/.zsh_env, ~/.fish_env

# Repository Settings
GITIGNORE_TEMPLATE: "standard"  # standard, node, python, rust, go, etc.
LICENSE_TYPE: "MIT"  # MIT, Apache-2.0, GPL-3.0, etc.

# Commit Message Settings
COMMIT_TYPES:
  - "feat"      # New feature
  - "fix"       # Bug fix
  - "docs"      # Documentation
  - "style"     # Code style
  - "refactor"  # Code restructuring
  - "perf"      # Performance
  - "test"      # Testing
  - "build"     # Build system
  - "ci"        # CI/CD
  - "chore"     # Maintenance

# Default Commit Scopes (customize per project)
COMMIT_SCOPES:
  - "core"
  - "api"
  - "ui"
  - "db"
  - "auth"
  - "config"
  - "docs"
  - "tests"
  - "utils"
  - "deps"
```

---

# =============================================
# 2. TERMINAL BLINDNESS PATCH (Critical Fix)
# =============================================

## 🪟 Windows Terminal Blindness Fix

When running commands on Windows, the run_command tool may append an extra quote or malform the command string, causing it to hang or fail.

**Solution**: Wrap the command in `{{WINDOWS.SHELL_WRAPPER}}` and append `{{WINDOWS.COMMAND_SUFFIX}}` to the end. This executes the command and then executes a comment, which safely absorbs any trailing garbage characters.

**Pattern:**
```bash
{{WINDOWS.SHELL_WRAPPER}} <your_command> {{WINDOWS.COMMAND_SUFFIX}}
```

**Examples:**

Instead of:
```bash
dir
```

Use:
```bash
{{WINDOWS.SHELL_WRAPPER}} dir {{WINDOWS.COMMAND_SUFFIX}}
```

Instead of:
```bash
python main.py
```

Use:
```bash
{{WINDOWS.SHELL_WRAPPER}} python main.py {{WINDOWS.COMMAND_SUFFIX}}
```

---

## 🐧 Linux / 🍎 macOS Terminal Blindness Fix

### For Bash (`~/.bashrc` or `~/.bash_profile`)
Add this at the **very top** of your file, before any other configurations:

```bash
# Coding Agent Terminal Blindness Fix
# Detects agent mode and uses clean shell to prevent output parsing issues
if [[ -n "$CODING_AGENT_MODE" ]] || [[ -n "$AI_AGENT_MODE" ]] || [[ -n "$CLAUDE_CODE_MODE" ]]; then
    export PS1='{{UNIX.SHELL_PROMPT}}'
    unset PROMPT_COMMAND
    export TERM="{{UNIX.TERM_TYPE}}"
    # Source your PATH/environment setup here (no interactive features)
    # Example: source {{UNIX.ENV_FILE}}
    return
fi
# Your normal bashrc config goes below this line
```

### For Zsh (`~/.zshrc`)
Add this at the **very top**:

```bash
# Coding Agent Terminal Blindness Fix
if [[ -n "$CODING_AGENT_MODE" ]] || [[ -n "$AI_AGENT_MODE" ]] || [[ -n "$CLAUDE_CODE_MODE" ]]; then
    export PS1='{{UNIX.SHELL_PROMPT}}'
    unset PROMPT_COMMAND
    unset precmd_functions
    unset preexec_functions
    export TERM="{{UNIX.TERM_TYPE}}"
    # Source your PATH/environment setup here
    # Example: source {{UNIX.ENV_FILE}}
    return
fi
# Your normal zshrc config goes below this line
```

### For Fish (`~/.config/fish/config.fish`)
Add this at the **very top**:

```fish
# Coding Agent Terminal Blindness Fix
if set -q CODING_AGENT_MODE; or set -q AI_AGENT_MODE; or set -q CLAUDE_CODE_MODE
    function fish_prompt
        echo '> '
    end
    function fish_right_prompt; end
    set -x TERM {{UNIX.TERM_TYPE}}
    # Source your PATH/environment setup here
    # Example: source {{UNIX.ENV_FILE}}
    return
end
# Your normal fish config goes below this line
```

---

### What These Rules Do

| Action | Purpose |
|--------|---------|
| Detect `$CODING_AGENT_MODE` | Identifies when the coding agent is running |
| Minimal `PS1`/prompt | Removes escape codes that corrupt output |
| Unset `PROMPT_COMMAND` | Stops OSC 633 sequence injection |
| Set `TERM=dumb` | Disables terminal capabilities |
| Early `return` | Skips loading fancy tools (starship, oh-my-posh, ble.sh, atuin, etc.) |

### Important: Separate Environment from Interactive Config

If you early-return, the agent won't have access to your `PATH` additions (cargo, npm, go, etc.).

**Solution**: Create a separate file for environment variables:

```bash
# ~/.bash_env (or ~/.zsh_env, ~/.fish_env)
export PATH="$HOME/.cargo/bin:$PATH"
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/go/bin:$PATH"
export NVM_DIR="$HOME/.nvm"
# ... other PATH and environment setup, NO output or escape codes
```

Then source it in the early-return block so the agent has access to all your tools.

### Environment Variable Names

Common environment variables used by coding agents (configured in AGENT_ENV_VARS):
- `$CODING_AGENT_MODE` - Generic flag for any coding agent
- `$AI_AGENT_MODE` - Alternative generic flag
- `$CLAUDE_CODE_MODE` - Claude Code specific
- `$CURSOR_MODE` - Cursor IDE specific
- `$AIDER_MODE` - Aider specific
- `$COPILOT_MODE` - GitHub Copilot specific

You can check for multiple:
```bash
if [[ -n "$CODING_AGENT_MODE" ]] || [[ -n "$CLAUDE_CODE_MODE" ]] || [[ -n "$CURSOR_MODE" ]]; then
    # Agent mode fixes
fi
```

---

# ====================================
# 3. NEW REPOSITORY INITIALIZATION
# ====================================

## Mandatory Steps for Every New Project

When starting any new project, **ALWAYS** follow this initialization sequence:

### Step 1 — Initialize Git Repository (FIRST STEP)
```bash
git init
```
- Do this **before** writing any code
- Make this your first action after creating the project directory

### Step 2 — Create Essential Files
Before first commit, create these files:
- `.gitignore` - Exclude unnecessary files
- `README.md` - Project overview and purpose
- `LICENSE` - Project license (if applicable)
- `.gitattributes` - Line ending configuration (if needed)

### Step 3 — Initial Commit (Required Format)
```bash
git add .
git commit -m "chore(init): initialize project repository

- Add .gitignore with [language/framework] exclusions
- Add README with project description
- Add [LICENSE_TYPE] license
- Set up basic project structure"
```

### Step 4 — Configure Repository Settings
```bash
# Set your identity (REQUIRED - use values from config variables)
git config user.name "{{GIT_USER_NAME}}"
git config user.email "{{GIT_USER_EMAIL}}"

# Set default branch name
git branch -M {{DEFAULT_BRANCH}}

# Configure line endings
git config core.autocrlf {{WINDOWS.LINE_ENDINGS}}  # For Windows
git config core.autocrlf {{UNIX.LINE_ENDINGS}}     # For Mac/Linux
```

**IMPORTANT**: All commits MUST use the configured author credentials:
- Name: `{{GIT_USER_NAME}}`
- Email: `{{GIT_USER_EMAIL}}`

### Step 5 — Create Branch Protection Structure
```bash
# Create development branch
git checkout -b {{DEVELOPMENT_BRANCH}}

# Return to main
git checkout {{DEFAULT_BRANCH}}
```

### Step 6 — Connect Remote Repository (When Ready)
```bash
git remote add origin <repository-url>
git push -u origin {{DEFAULT_BRANCH}}
```

---

## New Project Commit Sequence

For a new project, your first 5 commits should typically be:

1. **Initial commit**: Repository structure and configuration
   ```
   chore(init): initialize project repository
   ```

2. **Project setup**: Core dependencies and build configuration
   ```
   build(init): add project dependencies and build configuration
   ```

3. **Project structure**: Directory structure and base files
   ```
   chore(structure): create project folder structure
   ```

4. **Documentation**: Initial documentation
   ```
   docs(init): add project documentation and setup instructions
   ```

5. **First functionality**: First working feature
   ```
   feat(core): implement initial [feature_name]
   ```

---

## Standard .gitignore Template

Create this `.gitignore` for every new project (adjust based on language):
```
# Dependencies
node_modules/
vendor/
*.egg-info/
venv/
env/

# Build outputs
dist/
build/
*.pyc
*.class
*.o
*.exe

# IDE and editors
.vscode/
.idea/
*.swp
*.swo
*~

# OS files
.DS_Store
Thumbs.db

# Environment and secrets
.env
.env.local
*.key
*.pem
secrets/
config/credentials.yml

# Logs
*.log
logs/

# Testing
coverage/
.coverage
*.test
.pytest_cache/

# Temporary files
tmp/
temp/
*.tmp
```

---

## Repository Initialization Checklist

Before writing any project code:
- [ ] Run `git init` in project root
- [ ] Create `.gitignore` file (use {{GITIGNORE_TEMPLATE}} template)
- [ ] Create `README.md` with project description
- [ ] Add {{LICENSE_TYPE}} LICENSE file (if open source)
- [ ] Configure Git with author: `{{GIT_USER_NAME}} <{{GIT_USER_EMAIL}}>`
- [ ] Make initial commit with proper message format
- [ ] Set up default branch ({{DEFAULT_BRANCH}})
- [ ] Create {{DEVELOPMENT_BRANCH}} branch
- [ ] Connect to remote repository (GitHub/GitLab/etc.)
- [ ] Add collaborators or team members
- [ ] Set up branch protection rules (if available)

### Never Start Coding Without:
1. Git initialization complete
2. Initial commit made
3. `.gitignore` configured
4. Remote repository connected (if working with team)

---

# ========================================
# 4. COMMIT MESSAGE REQUIREMENTS (Strict)
# ========================================

Every commit must follow this format:

```
<type>(<scope>): <subject>

[optional body]

[optional footer]
```

## Type (Required)
Must be one of: `{{COMMIT_TYPES}}`

- **feat**: New feature or functionality
- **fix**: Bug fix
- **docs**: Documentation changes only
- **style**: Code style changes (formatting, whitespace, etc.)
- **refactor**: Code restructuring without changing behavior
- **perf**: Performance improvements
- **test**: Adding or modifying tests
- **build**: Build system or dependency changes
- **ci**: CI/CD configuration changes
- **chore**: Maintenance tasks, tooling updates

## Scope (Required)
Must be one of: `{{COMMIT_SCOPES}}`

Specify the module or component affected. Examples by project type:

**Web Applications:**
- `auth`: Authentication/authorization
- `api`: API endpoints
- `ui`: User interface components
- `db`: Database schema/queries
- `config`: Configuration files

**Libraries/SDKs:**
- `core`: Core functionality
- `utils`: Utility functions
- `types`: Type definitions
- `api`: Public API surface

**Data/ML Projects:**
- `pipeline`: Data pipeline
- `model`: Model training/inference
- `preprocessing`: Data preprocessing
- `validation`: Data validation

**General:**
- `docs`: Documentation
- `tests`: Test suites
- `deps`: Dependencies

## Subject (Required)
- Use imperative mood ("add" not "added" or "adds")
- Start with lowercase
- Maximum {{MAX_COMMIT_SUBJECT_LENGTH}} characters
- No period at the end
- Be specific and descriptive

---

# ===============================
# 5. COMMIT FREQUENCY RULES
# ===============================

### Commit After Every:

1. **Feature Implementation**
   - Each new feature or capability
   - Example: `feat(auth): add OAuth2 authentication flow`

2. **Bug Fix**
   - Each resolved issue
   - Example: `fix(api): correct pagination offset calculation`

3. **Refactoring Session**
   - After restructuring code for better maintainability
   - Example: `refactor(utils): extract validation logic to separate module`

4. **Documentation Update**
   - New or updated documentation
   - Example: `docs(api): add usage examples for REST endpoints`

5. **Test Addition**
   - New test cases or test suites
   - Example: `test(auth): add integration tests for login flow`

6. **Configuration Change**
   - Updates to project configuration
   - Example: `build(deps): upgrade React to v18.2`

7. **Performance Optimization**
   - After each optimization effort
   - Example: `perf(db): add indexes for frequently queried columns`

8. **UI Changes**
   - Visual or interaction updates
   - Example: `feat(ui): add loading spinner for async operations`

---

# ========================
# 6. BEST PRACTICES
# ========================

## DO:
- ✅ Commit early and often
- ✅ Write clear, descriptive messages
- ✅ Keep commits focused on a single change
- ✅ Reference issue numbers when applicable
- ✅ Test before committing
- ✅ Use present tense imperative mood
- ✅ Commit working code (compiles and runs)

## DON'T:
- ❌ Commit broken code
- ❌ Mix unrelated changes in one commit
- ❌ Use vague messages like "fix stuff" or "update"
- ❌ Commit generated files or build artifacts
- ❌ Wait too long between commits
- ❌ Commit sensitive data or credentials
- ❌ Use past tense ("fixed", "added")

---

# ===============================
# 7. EXAMPLE COMMIT MESSAGES
# ===============================

## Good Examples:
```
feat(auth): implement JWT token refresh mechanism

fix(api): resolve race condition in concurrent requests
- Add mutex lock for shared resource access
- Update documentation for thread-safe usage
- Fixes #42

refactor(ui): simplify component state management

perf(db): cache frequently accessed user preferences
- Reduces query time by 60%
- Implements Redis cache with 1-hour TTL

docs(README): add installation instructions for Docker

test(api): add end-to-end tests for payment flow

style(core): format code according to ESLint rules

build(deps): update dependencies to latest stable versions
- Includes security patches
- Breaking changes: see CHANGELOG.md
```

## Bad Examples:
```
❌ update stuff
❌ fixed bugs
❌ WIP
❌ asdfasdf
❌ Fixed the thing that wasn't working
❌ Added new feature and fixed 3 bugs and updated docs
```

---

# ============================================
# 8. CODE QUALITY RULES — SENIOR ENGINEERING
# ============================================

## Architectural Principles (Mandatory)

Every code change must adhere to:

### SOLID Principles
- **S**ingle Responsibility: Each class/function does ONE thing
- **O**pen/Closed: Open for extension, closed for modification
- **L**iskov Substitution: Subtypes must be substitutable for base types
- **I**nterface Segregation: Many specific interfaces > one general interface
- **D**ependency Inversion: Depend on abstractions, not concretions

### Design Patterns (Use Appropriately)
- Factory Pattern for object creation
- Strategy Pattern for algorithm variations
- Observer Pattern for event handling
- Singleton Pattern (use sparingly and justify)
- Dependency Injection for loose coupling

### Code Organization
```
✅ High cohesion within modules
✅ Low coupling between modules
✅ Clear separation of concerns
✅ Layered architecture (presentation → business → data)
✅ Domain-driven design where applicable
```

---

## Naming Conventions (Non-Negotiable)
```
✅ GOOD:
- calculateTotalPrice()
- userAccountBalance
- MAX_RETRY_ATTEMPTS
- UserRepository
- isAuthenticated()

❌ BAD:
- calc()
- uab
- temp
- doStuff()
- data
- x, y, z (without context)
```

**Rules:**
- Variables: camelCase, descriptive, noun-based
- Functions: camelCase, verb-based, intention-revealing
- Classes: PascalCase, noun-based
- Constants: UPPER_SNAKE_CASE
- Booleans: is/has/can prefix
- No single-letter names except loop indices
- No abbreviations unless universally known
- Max length: {{MAX_VARIABLE_NAME_LENGTH}} characters

---

## Function Quality Standards

**Every function must:**
```javascript
// ✅ GOOD: Single responsibility, clear purpose, documented
/**
 * Calculates the total price including tax and discount.
 * 
 * @param {number} basePrice - Original price before adjustments
 * @param {number} taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
 * @param {number} discountPercent - Discount percentage (0-100)
 * @returns {number} Final price rounded to 2 decimal places
 * @throws {InvalidPriceError} If basePrice is negative
 */
function calculateTotalPrice(basePrice, taxRate = 0, discountPercent = 0) {
  validatePrice(basePrice);
  
  const discountAmount = basePrice * (discountPercent / 100);
  const priceAfterDiscount = basePrice - discountAmount;
  const taxAmount = priceAfterDiscount * taxRate;
  const totalPrice = priceAfterDiscount + taxAmount;
  
  return Math.round(totalPrice * 100) / 100;
}

// ❌ BAD: Multiple responsibilities, unclear, no validation
function calc(p, t, d) {
  return p - p * d / 100 + (p - p * d / 100) * t;
}
```

**Function Requirements:**
- Maximum {{MAX_FUNCTION_LINES}} lines (excluding comments)
- Maximum {{MAX_FUNCTION_PARAMETERS}} parameters (use objects for more)
- Maximum {{MAX_NESTING_LEVELS}} levels of nesting
- Single responsibility only
- No side effects unless clearly named (e.g., `updateUserStatus()`)
- Return early for error conditions
- Pure functions preferred (same input = same output)

---

## Error Handling (Required)

```javascript
// ✅ GOOD: Specific errors, proper handling, informative messages
class InvalidPriceError extends Error {
  constructor(price, reason) {
    super(`Invalid price: ${reason}`);
    this.name = 'InvalidPriceError';
    this.price = price;
  }
}

function validatePrice(price) {
  if (price === null || price === undefined) {
    throw new InvalidPriceError(price, 'Price cannot be null or undefined');
  }
  if (price < 0) {
    throw new InvalidPriceError(price, `Price must be non-negative, got ${price}`);
  }
  if (!Number.isFinite(price)) {
    throw new InvalidPriceError(price, 'Price must be a valid number');
  }
}

// ❌ BAD: Generic errors, poor messages
function validatePrice(price) {
  if (!price || price < 0) throw new Error('bad price');
}
```

**Error Handling Rules:**
- Create custom error classes for domain-specific errors
- Never swallow exceptions silently
- Log errors with context (timestamp, user, operation)
- Use try-catch at appropriate boundaries
- Fail fast with clear error messages
- No empty catch blocks
- Always clean up resources (use finally or RAII)

---

## Documentation Standards

**Every file must have:**
```javascript
/**
 * @file PriceCalculator.js
 * @description Handles price calculations including tax and discounts
 * @author {{GIT_USER_NAME}} <{{GIT_USER_EMAIL}}>
 * @version 1.2.0
 * @since 2024-01-15
 */
```

**Every public function must have:**
- Purpose description
- Parameter descriptions with types
- Return value description
- Possible exceptions
- Usage examples (for complex functions)
- Time/space complexity (for algorithms)

**Every complex algorithm must have:**
- High-level explanation
- Why this approach was chosen
- References to papers/sources if applicable
- Known limitations

---

## Testing Requirements (Mandatory)

**Test Coverage Rules:**
- Minimum {{MIN_TEST_COVERAGE}}% code coverage
- 100% coverage for critical paths
- Unit tests for every public function
- Integration tests for component interactions
- Edge case testing (null, zero, negative, max values)
- Performance tests for algorithms

```javascript
// ✅ GOOD: Comprehensive testing
describe('calculateTotalPrice', () => {
  describe('valid inputs', () => {
    it('should calculate price with tax and no discount', () => {
      const result = calculateTotalPrice(100, 0.08, 0);
      expect(result).toBe(108);
    });
    
    it('should calculate price with discount and tax', () => {
      const result = calculateTotalPrice(100, 0.08, 10);
      expect(result).toBe(97.2);
    });
  });
  
  describe('edge cases', () => {
    it('should throw InvalidPriceError for null price', () => {
      expect(() => calculateTotalPrice(null, 0.08, 0))
        .toThrow(InvalidPriceError);
    });
    
    it('should throw InvalidPriceError for negative price', () => {
      expect(() => calculateTotalPrice(-10, 0.08, 0))
        .toThrow(InvalidPriceError);
    });
    
    it('should handle zero price', () => {
      const result = calculateTotalPrice(0, 0.08, 0);
      expect(result).toBe(0);
    });
  });
  
  describe('performance', () => {
    it('should calculate 10000 prices in under 100ms', () => {
      const start = Date.now();
      for (let i = 0; i < 10000; i++) {
        calculateTotalPrice(100, 0.08, 10);
      }
      expect(Date.now() - start).toBeLessThan(100);
    });
  });
});
```

---

## Performance Standards

**Every commit must consider:**
- Time complexity: Document O(n) notation
- Space complexity: Avoid memory leaks
- Algorithm efficiency: Use optimal data structures
- Caching: Cache expensive computations
- Lazy loading: Load resources only when needed
- Database queries: Optimize N+1 queries
- Network calls: Batch when possible

**Performance Benchmarks:**
```javascript
// ✅ GOOD: Optimized with complexity analysis
/**
 * Finds duplicate items using a hash set.
 * Time: O(n) 
 * Space: O(n) for hash set
 */
function findDuplicates(items) {
  const seen = new Set();
  const duplicates = new Set();
  
  for (const item of items) { // O(n)
    if (seen.has(item)) { // O(1)
      duplicates.add(item);
    } else {
      seen.add(item);
    }
  }
  
  return Array.from(duplicates);
}

// ❌ BAD: Nested loops O(n²) without justification
function findDuplicates(items) {
  const duplicates = [];
  for (let i = 0; i < items.length; i++) {
    for (let j = i + 1; j < items.length; j++) {
      if (items[i] === items[j] && !duplicates.includes(items[i])) {
        duplicates.push(items[i]);
      }
    }
  }
  return duplicates;
}
```

---

## Security Best Practices

**Required Security Measures:**
- Input validation on all external data
- Parameterized queries (no SQL injection)
- Sanitize user input (no XSS)
- Use environment variables for secrets
- No hardcoded credentials
- Implement rate limiting
- Use HTTPS for all network calls
- Validate file uploads (type, size)
- Implement proper authentication/authorization
- Log security events

---

## Code Review Checklist

**Before committing, verify:**
- [ ] No magic numbers (use named constants)
- [ ] No code duplication (DRY principle)
- [ ] No commented-out code
- [ ] No TODO comments without tickets
- [ ] No console.log or debug statements
- [ ] Proper error handling throughout
- [ ] All edge cases considered
- [ ] Performance implications assessed
- [ ] Security vulnerabilities checked
- [ ] Backward compatibility maintained
- [ ] Breaking changes documented
- [ ] Memory leaks prevented
- [ ] Thread safety considered (if applicable)

---

## Advanced Code Patterns

**Prefer:**
```javascript
// ✅ Immutability
const updatedUser = { ...user, lastLogin: new Date() };

// ✅ Functional composition
const processOrder = compose(
  validateOrder,
  calculateTotals,
  applyDiscounts,
  generateInvoice
);

// ✅ Early returns
function processPayment(order) {
  if (!order) return null;
  if (!order.isValid) return order;
  if (order.total <= 0) throw new Error('Invalid total');
  
  return chargePaymentMethod(order);
}

// ✅ Guard clauses
function calculateDiscount(order) {
  if (!order) throw new InvalidOrderError();
  if (!this.isInitialized) throw new NotInitializedError();
  if (order.items.length === 0) return 0;
  
  return this.applyDiscountRules(order);
}
```

**Avoid:**
```javascript
// ❌ Nested conditionals
if (user) {
  if (user.isActive) {
    if (user.hasPermission) {
      // deeply nested code
    }
  }
}

// ❌ Mutating state
user.lastLogin = new Date(); // mutates original

// ❌ God objects/classes
class ApplicationManagerControllerHandler {
  // 50 methods, 30 properties
}
```

---

# =============================
# 9. PRE-COMMIT CHECKLIST
# =============================

Before every commit:

## Code Quality
- [ ] Code follows SOLID principles
- [ ] All functions under {{MAX_FUNCTION_LINES}} lines
- [ ] Maximum {{MAX_NESTING_LEVELS}} levels of nesting
- [ ] No code duplication (DRY)
- [ ] Descriptive names for all variables/functions
- [ ] No magic numbers (use constants)
- [ ] Proper error handling implemented
- [ ] No commented-out code

## Documentation
- [ ] All public functions documented
- [ ] Complex algorithms explained
- [ ] Comments explain "why" not "what"
- [ ] README updated if behavior changes

## Testing
- [ ] All tests pass
- [ ] New tests added for new functionality
- [ ] Edge cases tested
- [ ] Code coverage ≥ {{MIN_TEST_COVERAGE}}%
- [ ] Performance benchmarks pass

## Security
- [ ] Input validation present
- [ ] No hardcoded secrets
- [ ] SQL queries parameterized
- [ ] User input sanitized

## Performance
- [ ] Time complexity documented
- [ ] No obvious performance bottlenecks
- [ ] Memory leaks prevented
- [ ] Efficient algorithms used

## General
- [ ] Code compiles without errors
- [ ] No debug code or console logs
- [ ] Code follows project style guidelines
- [ ] Commit message follows format rules
- [ ] Changes are focused and atomic

---

# ===========================
# 10. BRANCH-SPECIFIC RULES
# ===========================

## Main/Master Branch ({{DEFAULT_BRANCH}})
- Only merge through pull requests
- Require code review approval
- All tests must pass
- Commit messages must be perfect

## Feature Branches
- Commit frequently (after each logical change)
- Use descriptive branch names: `feature/<scope>-<description>`
- Squash commits before merging if they're too granular

## Development Branch ({{DEVELOPMENT_BRANCH}})
- Integration branch for features
- Must be stable and pass all tests
- Regular merges to {{DEFAULT_BRANCH}}

## Hotfix Branches
- Use `hotfix/<issue-number>-<description>`
- Commit immediately after fix verification
- Include issue reference in commit message

---

# ========================
# 11. TOOLS INTEGRATION
# ========================

## Git Hooks (Recommended)
Set up pre-commit hooks to enforce:
- Commit message format validation
- Code linting
- Test execution
- No large files

## Commit Template
Configure Git to use a commit template:
```bash
git config commit.template .gitmessage.txt
```

## Semantic Versioning Impact

Commits trigger version changes:
- `feat`: Minor version bump (0.X.0)
- `fix`: Patch version bump (0.0.X)
- `BREAKING CHANGE`: Major version bump (X.0.0)

---

# =======================================
# 12. ANTIGRAVITY AI ASSISTANT BEHAVIOR
# =======================================

### The AI assistant **MUST**:
- Follow all commit standards automatically
- Detect platform (Windows/Unix) and apply appropriate blindness fixes
- Detect agent mode using configured `AGENT_ENV_VARS`
- Prefer minimal shells when in agent mode
- Enforce all code quality restrictions (function length, nesting, naming, etc.)
- Automatically validate commit messages before committing
- Propose refactors if code violates quality rules
- Use configuration variables for all values
- Document all code with proper JSDoc/docstrings
- Write tests for all new functionality
- Check for security vulnerabilities
- Optimize for performance where applicable

### The AI assistant **MUST NOT**:
- Output ANSI escape sequences or terminal control codes
- Generate commit messages that violate the format
- Modify shell prompts improperly
- Produce code exceeding configured limits (lines, parameters, nesting)
- Bypass safety or quality standards
- Commit code without proper error handling
- Skip testing requirements
- Introduce security vulnerabilities
- Use magic numbers or unclear variable names
- Create functions with side effects