Update Agent Rules documentation to include organization rules and hierarchy (#1246)

Co-authored-by: codegen-sh[bot] <131295404+codegen-sh[bot]@users.noreply.github.com>
Co-authored-by: Jay Hack <jay@codegen.com>

Author: codegen-sh[bot]

docs/settings/repo-rules.mdx

@@ -1,39 +1,100 @@
 ---
-title: "Repository Rules"
-sidebarTitle: "Repo Rules"
+title: "Agent Rules"
+sidebarTitle: "Agent Rules"
 icon: "shield-check"
 ---
 
-Repository Rules in Codegen act as a persistent set of instructions or a "system prompt" for the AI agent whenever it operates on a specific repository. These rules guide the agent's behavior by enforcing coding standards and repository-specific conventions through automated reminders to the language model (LLM) during each task.
+Agent Rules in Codegen act as persistent instructions or "system prompts" for the AI agent, guiding its behavior by enforcing coding standards, conventions, and preferences. These rules are automatically included in the agent's context during each task to ensure consistent behavior across your organization and repositories.
 
-Codegen supports two types of repository rules:
-1. **Manual Repository Rules** - configured through the web interface
-2. **Automatic Rule File Detection** - automatically discovered from your repository files
+## Rule Hierarchy
+
+Codegen supports a hierarchical rule system with three levels:
+
+1. **User Rules** - Personal preferences that apply to all your work across organizations
+2. **Organization Rules** - Apply to all repositories within your organization  
+3. **Repository Rules** - Apply to a specific repository and override higher-level rules when conflicts exist
+
+<Note>
+  **Rule Precedence**: Repository rules take precedence over organization rules, which take precedence over user rules when conflicts exist. This allows you to set personal defaults, organization-wide standards, and repository-specific customizations.
+</Note>
+
+## Types of Rules
+
+Each level supports two types of rule configuration:
+
+### Manual Rules
+Rules configured directly through the Codegen web interface at [codegen.com/repos](https://codegen.com/repos) (for repository rules) or organization settings (for organization rules).
+
+### Automatic Rule File Detection  
+Rules automatically discovered from files in your repository (repository level only).
 
 <Frame caption="Update repo rules at codegen.com/repos">
   <img src="/images/repo-rules.png" />
 </Frame>
 
-## How Repository Rules Work
+## How Agent Rules Work
+
+When an agent is assigned a task, all applicable rules are automatically included in the agent's context as "Mandatory User Rules." The agent sees these rules alongside the actual task or prompt it receives, ensuring consistent behavior.
+
+**Rule Resolution Process:**
+1. **User Rules** are loaded first (if configured in your personal settings)
+2. **Organization Rules** are loaded next (if configured for your organization)
+3. **Repository Rules** are loaded next (if configured for the specific repository)
+4. **Higher-level rules override lower-level rules** when conflicts exist (Repository > Organization > User)
+5. **Automatic rule files** are discovered and included (repository level only)
+6. All rules are combined and presented to the agent as mandatory constraints
+
+For example, if you have a user rule "Always use semicolons in JavaScript," your organization has a rule "Use TypeScript for all new code," and a specific repository has a rule "Use JavaScript for this legacy project," the repository rule takes precedence, followed by the organization rule, then your personal user rule.
+
+## Configuring Agent Rules
+
+### User Rules
+
+User rules are personal preferences that apply to all your work across organizations. These are perfect for setting your individual coding style, preferred tools, or workflow preferences.
+
+**To configure user rules:**
+1. Navigate to your personal settings in the Codegen web interface
+2. Look for the "User Rules" or "Personal Agent Rules" section
+3. Enter your personal preferences and coding standards
+4. Click "Save" to apply them across all organizations and repositories you work with
+
+<Tip>
+  User rules are ideal for personal preferences like "Always include detailed commit messages," "Prefer functional programming patterns," or "Use specific linting configurations."
+</Tip>
+
+<Note>
+  **Coming Soon**: User-level rules are currently being implemented and will be available in an upcoming release. The infrastructure is in place, and this feature will allow you to set personal coding preferences that follow you across all organizations.
+</Note>
+
+### Organization Rules
 
-When an agent is assigned a task on a repository with defined rules, those rules are automatically prepended or made available to the LLM as part of its context. This means the agent "sees" these rules alongside the actual task or prompt it receives.
+Organization rules apply to all repositories within your organization and serve as default behavior guidelines.
 
-For example, if you have a rule like "Always use tabs for indentation," the agent will be reminded of this preference before it starts writing or modifying code in that repository.
+**To configure organization rules:**
+1. Navigate to your organization settings in the Codegen web interface
+2. Look for the "Organization Rules" section
+3. Enter your organization-wide rules in the text area
+4. Click "Save" to apply them to all repositories in your organization
 
-## Accessing and Configuring Repository Rules
+<Tip>
+  Organization rules are perfect for setting coding standards, commit message conventions, or testing requirements that should apply across all your repositories.
+</Tip>
 
-You can typically find and configure Repository Rules within the settings page for each specific repository in the Codegen web UI.
+### Repository Rules
 
-1.  Navigate to [codegen.com/repos](https://codegen.com/repos).
-2.  Select the repository for which you want to set rules.
-3.  Look for a section titled "Repository rules" or similar in the repository's settings.
+Repository rules apply to a specific repository and override any conflicting organization rules.
+
+**To configure repository rules:**
+1. Navigate to [codegen.com/repos](https://codegen.com/repos)
+2. Select the repository for which you want to set rules
+3. Look for the "Repository Rules" section in the repository's settings
+4. Enter your repository-specific rules in the text area
+5. Click "Save" to apply them
 
 <Frame caption="Update repo rules at codegen.com/repos">
   <img src="/images/repo-rules.png" />
 </Frame>
 
-In the text area provided (as shown in the image), you can specify any rules you want the agent to follow for this repository. Click "Save" to apply them.
-
 ## Automatic Rule File Detection
 
 In addition to manual repository rules, Codegen automatically discovers and includes agent rule files from your repository when the agent starts working on it. This happens automatically whenever the `set_active_codebase` tool is used.
@@ -105,30 +166,63 @@ When rules are discovered, they are displayed in the AgentTrace under the `SetAc
 
 ## Common Use Cases and Examples
 
-Repository rules are flexible and can be used for various purposes:
+Agent rules are flexible and can be used for various purposes across different levels:
+
+### User-Level Rules Examples
+
+Perfect for personal preferences that should apply across all your work:
 
-- **Enforcing Linting/Formatting:**
-  - "Remember to run the linter with `npm run lint` before committing."
-  - "Ensure all Python code follows PEP 8 guidelines. Use `black` for formatting."
-- **Specifying Commit Message Conventions:**
+- **Personal Coding Style:**
+  - "I prefer functional programming patterns over object-oriented when possible."
+  - "Always include detailed JSDoc comments for functions with more than 2 parameters."
+- **Workflow Preferences:**
+  - "Include performance considerations in code reviews for any loops or database queries."
+  - "Prefer explicit error handling over try-catch blocks when the error is expected."
+- **Tool Preferences:**
+  - "Use my preferred linting configuration and code formatting style."
+  - "Always suggest using TypeScript strict mode for new projects."
+
+### Organization-Level Rules Examples
+
+Perfect for organization-wide standards that should apply to all repositories:
+
+- **Coding Standards:**
+  - "All code must follow our organization's style guide. Use Prettier for JavaScript/TypeScript formatting."
+  - "All API endpoints must include proper error handling and logging."
+- **Security Requirements:**
+  - "Never commit API keys, passwords, or other secrets to the repository."
+  - "All database queries must use parameterized statements to prevent SQL injection."
+- **Process Requirements:**
   - "All commit messages must follow the Conventional Commits specification."
-  - "Prefix commit messages with the related Linear issue ID (e.g., `ENG-123: ...`)."
-- **Highlighting Project-Specific Information:**
-  - "This repository uses TypeScript. All new backend code should be in the `/server/src` directory."
+  - "Every PR must include tests for new functionality."
+
+### Repository-Level Rules Examples
+
+Perfect for repository-specific requirements that may override organization defaults:
+
+- **Technology-Specific Rules:**
+  - "This is a Python project. Use `black` for formatting and `pytest` for testing."
+  - "This legacy repository uses JavaScript instead of our organization's TypeScript standard."
+- **Project-Specific Information:**
+  - "All new backend code should be in the `/server/src` directory."
   - "Avoid using deprecated function `old_function()`. Use `new_function()` instead."
-- **Code Style Preferences:**
-  - "Don't write super long strings, as this will break pre-commit. Do triple-quoted strings with newlines, non-indented, instead!" (As seen in your example image)
-  - "Prefer functional components over class components in React."
-- **Reminders for Testing:**
-  - "Ensure all new features have corresponding unit tests."
-  - "Run integration tests with `npm run test:integration` after significant changes."
+- **Build and Deployment:**
+  - "Run `npm run build` before committing to ensure the build passes."
+  - "This repository deploys automatically on merge to main - ensure all tests pass."
+
+### Rule Hierarchy in Action
+
+Here's how user, organization, and repository rules work together:
+
+**User Rule:** "I prefer detailed error messages with context"  
+**Organization Rule:** "Use TypeScript for all new code"  
+**Repository Rule:** "This legacy project uses JavaScript - do not convert existing files"  
+**Result:** The agent will use JavaScript for this specific repository (repository rule wins), but will still include detailed error messages (user rule applies) since there's no conflict.
 
 <Tip>
-  Keep your repository rules concise and clear. Overly complex or numerous rules
-  might confuse the agent or lead to suboptimal performance. Focus on the most
-  critical guidelines for each repository.
+  Keep your rules concise and clear. Overly complex or numerous rules might confuse the agent or lead to suboptimal performance. Focus on the most critical guidelines for your organization and repositories.
 </Tip>
 
 <Note>
-  Both manual repository rules and automatic rule files are applied *in addition* to any global prompting strategies or agent capabilities. They provide a repository-specific layer of instruction that helps ensure consistent behavior across your codebase.
+  All agent rules (user, organization, repository, and automatic rule files) are applied *in addition* to any global prompting strategies or agent capabilities. They provide a hierarchical layer of instruction that helps ensure consistent behavior across your personal work, organization, and codebases.
 </Note>{" "}