docs: Address PR comment about admin naming convention fragility

Added comprehensive documentation for admin tool/resource naming conventions
to address PR reviewer's concern about relying on naming patterns.

Changes:
- **Added Code Conventions section to CLAUDE.md**: Documents admin_* prefix
  convention for tools and admin://* URI scheme for resources
- **Added inline comments**: Explains naming convention in utils.py and
  resources/__init__.py with notes about future decorator approach
- **Documented enforcement**: Clarifies that code review enforces conventions
  and has_admin_credentials() performs actual credential verification

Rationale:
- Naming convention is reasonable trade-off vs decorator complexity
- Convention is consistently followed throughout codebase
- Documented for maintainability and code review enforcement
- Suggests future decorator-based approach if convention becomes insufficient

Addresses PR comment: "The filtering logic assumes admin tools are prefixed
with 'admin_'. This could be made more robust by using a more explicit
mechanism (decorator, metadata, or registry)."

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: drernie

AGENTS.md

@@ -274,6 +274,25 @@ Key execution guidelines:
 - Suggest improvements that align with these principles
 - When unsure, ask for clarification rather than assuming
 
+## Code Conventions
+
+### Admin Tool and Resource Naming
+
+**Convention**: Admin-only functionality follows consistent naming patterns for filtering based on user credentials.
+
+- **Tools**: Admin tools use `admin_*` function name prefix (e.g., `admin_user_create`, `admin_role_list`)
+- **Resources**: Admin resources use `admin://*` URI scheme (e.g., `admin://users`, `admin://roles`)
+
+**Rationale**: These conventions enable credential-based filtering at registration time without requiring decorators or metadata systems. Non-admin users see a clean interface without admin clutter.
+
+**Enforcement**:
+- Code review ensures all admin functions follow naming convention
+- `has_admin_credentials()` in `QuiltService` performs actual credential verification (not just import checks)
+- Tools filtered in `utils.register_tools_from_module()` based on name prefix
+- Resources filtered in `resources.create_default_registry()` at registration time
+
+**Future Consideration**: If naming convention becomes insufficient, consider decorator-based approach (`@admin_required`) or resource-level metadata for more robustness.
+
 ## Summary
 
 The key is to write clean, testable, functional code that evolves through small, safe increments. Every change should be driven by a test that describes the desired behavior, and the implementation should be the simplest thing that makes that test pass. When in doubt, favor simplicity and readability over cleverness.

src/quilt_mcp/resources/__init__.py

@@ -60,6 +60,9 @@ def create_default_registry() -> ResourceRegistry:
     has_admin = service.has_admin_credentials()
 
     # Register admin resources only if user has credentials
+    # NOTE: Admin resources follow URI convention of 'admin://*' scheme.
+    # This is enforced by code review and documented in CLAUDE.md.
+    # Future: Consider resource-level metadata (@requires_admin) for more flexibility.
     if has_admin:
         registry.register("admin://users", AdminUsersResource())
         registry.register("admin://roles", AdminRolesResource())

src/quilt_mcp/utils.py

@@ -155,6 +155,9 @@ def make_predicate(mod: Any) -> Callable[[Any], bool]:
 
         for name, func in functions:
             # Skip admin tools if user lacks admin credentials
+            # NOTE: Admin tools follow naming convention of 'admin_*' prefix.
+            # This is enforced by code review and documented in CLAUDE.md.
+            # Future: Consider decorator-based approach (@admin_required) for more robustness.
             if name.startswith('admin_') and not has_admin:
                 if verbose:
                     print(f"Skipped admin tool: {module.__name__}.{name} (no admin credentials)", file=sys.stderr)