docs: add brand guardian agent documentation

[kaochannel154]

User description

Changes

• Add brand guardian agent for reviewing logo usage compliance
• Include checklist for brand guideline compliance
• Add brand-specific notes for Vercel, GitHub, and OpenAI
• Define output format and tone guidelines
• Translate entire document to English

---

PR Type

Documentation

---

Description

• Add brand guardian agent documentation for logo compliance review

• Define comprehensive checklist for brand guideline evaluation

• Include brand-specific guidelines for Vercel, GitHub, OpenAI

• Specify output format, tone, and evaluation principles

---

Diagram Walkthrough

flowchart LR
  A["Brand Guardian Agent"] --> B["Logo Compliance Review"]
  B --> C["Checklist Evaluation"]
  C --> D["Brand-Specific Guidelines"]
  D --> E["Markdown Output Report"]

Loading

File Walkthrough

Relevant files

Documentation

brand-guardian.md Brand guardian agent documentation with compliance framework .claude/agents/brand-guardian.md Introduces brand guardian agent for reviewing logo usage compliance with external brands Defines role, goals, and principles for brand guideline enforcement Provides comprehensive checklist covering source, modification, notation, context, contrast, spacing, and misrepresentation Specifies structured Markdown output format with assessment, issues, proposals, and checked items sections Documents brand-specific guidelines for Vercel, GitHub, and OpenAI with references Establishes polite and proposal-oriented tone with prohibited absolute expressions +82/-0

---

Note

Adds a Brand Guardian agent spec detailing role, review checklist, standardized output template, brand-specific logo guidelines, and tone.

• Documentation:
  • New agent spec in .claude/agents/brand-guardian.md defining role, goals, and principles for logo/brand usage review.
  • Checklist for compliance (source, modification, notation, context, contrast, spacing, misrepresentation).
  • Standardized output template for assessments, issues, improvement proposals, and checked items.
  • Brand-specific notes for Vercel, GitHub, and OpenAI with key usage rules and references.
  • Tone guidelines for polite, neutral, proposal-oriented feedback.

^{Written by Cursor Bugbot for commit f6a8a71. This will update automatically on new commits. Configure here.}

Summary by CodeRabbit

Release Notes

• New Features

  • Added Brand Guardian agent for automated logo usage review and brand compliance assessment.

• Documentation

  • Included comprehensive guidelines covering brand-specific standards, evaluation criteria, quality constraints, and standardized assessment formats for logo usage review.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f6a8a71

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.

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

💥 An error occurred when fetching the changed packages and changesets in this PR

Some errors occurred when validating the changesets config:
The package or glob expression "giselles-ai" is specified in the `ignore` option but it is not found in the project. You may have misspelled the package name or provided an invalid glob expression. Note that glob expressions must be defined according to https://www.npmjs.com/package/micromatch.

[giselles-ai]

Finished running flow.

Step 1
🟢	On Pull Request Opened Status: Success Updated: Nov 11, 2025 7:57am
Step 2
🟢	Manual QA Status: Success Updated: Nov 11, 2025 7:59am
🟢	Prompt for AI Agents Status: Success Updated: Nov 11, 2025 7:59am
Step 3
🟢	Create a Comment for PR Status: Success Updated: Nov 11, 2025 8:00am
Step 4
🟢	Create Pull Request Comment Status: Success Updated: Nov 11, 2025 8:00am

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
giselle	Ready	Preview	Comment	Nov 11, 2025 8:02am
ui	Ready	Preview	Comment	Nov 11, 2025 8:02am

[Copilot]

Pull Request Overview

This PR introduces comprehensive documentation for a brand guardian agent that reviews logo usage compliance with brand guidelines. The agent helps ensure proper use of external brand assets (logos, names) from services like Vercel, GitHub, and OpenAI before public release.

Key changes:

• Establishes a structured review framework with defined roles, goals, and principles for brand compliance
• Provides a standardized checklist covering seven critical aspects of brand usage
• Includes brand-specific guidelines for Vercel, GitHub, and OpenAI with official reference links

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Vercel brand guidelines URL appears to be incomplete or incorrect. The correct URL for Vercel's brand assets should be verified. Consider using https://vercel.com/design/brands or the official brand guidelines page.

Suggested change

	- ref: https://vercel.com/design
	- ref: https://vercel.com/design/brands

[qodo-merge-for-open-source]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

A new Markdown document is introduced at .claude/agents/brand-guardian.md that defines a Brand Guardian agent for evaluating logo usage compliance with brand guidelines. The document specifies the agent's role, goals, principles, evaluation checklist, required output format, brand-specific notes, and tone requirements.

Changes

Cohort / File(s)	Summary
Brand Guardian Agent Definition \.claude/agents/brand-guardian\.md	New documentation file defining the Brand Guardian agent with role description, evaluation goals, assessment principles, logo usage checklist, output format specifications (Markdown sections for Overall Assessment, Issues, Improvement Proposals), brand-specific guidelines for Vercel, GitHub, and OpenAI, and tone/constraint requirements.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

This is a straightforward documentation file with no code logic or dependencies. The review focuses on verifying the clarity and completeness of the agent specification, checklist accuracy, and alignment with intended brand review workflow.

Suggested labels

review effort 2/5

Suggested reviewers

• shige

Poem

🐰 A guardian emerges, bold and keen,
To check if logos shine supreme,
With checklists precise and rules so clear,
Brand safety stands without a fear! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title 'docs: add brand guardian agent documentation' clearly and specifically summarizes the main change—adding documentation for a new Brand Guardian agent.
Description check	✅ Passed	The pull request description provides comprehensive information including summary, PR type, detailed description, diagram, file walkthrough, and note section covering all required template sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/brand-guardian-agent

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e1f283f and f6a8a71.

📒 Files selected for processing (1)

• .claude/agents/brand-guardian.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

.claude/agents/brand-guardian.md

64-64: Bare URL used

(MD034, no-bare-urls)

---

70-70: Bare URL used

(MD034, no-bare-urls)

---

76-76: Bare URL used

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: check

🔇 Additional comments (3)

.claude/agents/brand-guardian.md (3)

35-56: Well-structured output format template.

The output format section provides a clear, actionable template for agents to follow. The three-part structure (Overall Assessment, Issues, Improvement Proposals) is well-suited for compliance reviews.

---

23-34: Comprehensive checklist covers key brand compliance aspects.

The checklist effectively captures the critical evaluation dimensions (source, modification, notation, context, contrast, spacing, misrepresentation). This provides a solid foundation for consistent brand guideline reviews.

---

64-64: I'll verify the review comment by examining the file and checking the URLs. Let me start with both tasks:

Now let me examine the actual file:

I need to examine the actual file to determine the context:

Based on my verification of the three URLs in question, I have gathered the necessary information to assess this review comment:

The Vercel URL (https://vercel.com/design) is correct — it hosts Vercel's design and brand guidelines content.

The GitHub URL (https://github.com/logos) is correct — it provides GitHub logos and usage guidelines.

The OpenAI URL (https://openai.com/brand) is correct — it contains language and assets for using the OpenAI brand.

However, the proposed fix in the review comment has a critical issue: MD034 (the markdownlint bare URL rule) is triggered when a URL isn't surrounded by angle brackets, and the fix is to add angle brackets like <http://example.com/>, not to wrap URLs in Markdown link syntax [URL](URL).

More importantly, these URLs appear to be in YAML ref: fields within a Claude Code agent definition file. The MD034 rule only triggers for text in Paragraph elements, Atx Heading elements, or SetExt Heading elements, not in YAML data structures. Wrapping URLs in Markdown link syntax within YAML values would be inappropriate and could break YAML parsing.

---

Likely an incorrect or invalid review comment.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[qodo-merge-for-open-source]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Resolve contradiction in agent instructions Resolve a contradiction in the agent's instructions. Instead of banning the word "violation", guide the agent on how to frame findings professionally to avoid confusing it, as one of its goals is to prevent "guideline violations". .claude/agents/brand-guardian.md [82] -Prohibited words: Absolute expressions like "wrong" or "violation". +When identifying issues, state them factually (e.g., "This usage does not comply with guideline X") rather than using accusatory language like "you did this wrong". Avoid overly strong or absolute statements where nuance is required. Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies a contradiction between the agent's goal to prevent violations and the instruction to avoid the word violation, which could confuse the agent and lead to less effective outputs.	Low
General	Merge overlapping checklist items for clarity Merge the overlapping checklist items 'Context' and 'Misrepresentation' into a single, clearer item to avoid confusing the agent and improve the quality of its analysis. .claude/agents/brand-guardian.md [30-33] -| Context | Does it imply partnership or official status? | -| Misrepresentation | Are there expressions or placements that could cause misunderstanding? | +| Misrepresentation | Does the usage imply a partnership, endorsement, or other relationship that doesn't exist? Could it cause any other misunderstanding? | Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly points out that the checklist items Context and Misrepresentation overlap, which can lead to confusion. Merging them improves the clarity and structure of the agent's instructions.	Low
More

[giselles-ai]

📋 Manual QA Checklist

Based on the changes in this PR, here are the key areas to test manually:

• File Location: Verify that the new file brand-guardian.md exists in the .claude/agents/ directory.
• Document Structure: Confirm the presence of all required sections: 1. Role, 2. Goals, 3. Principles, 4. Checklist, 5. Output format, 6. Brand-specific notes, 7. Tone.
• Checklist Table Rendering: Ensure the "4. Checklist" section's table renders correctly with all seven specified items.
• Output Format Example: Check that the example in "5. Output format" is within a Markdown code block and includes Overall Assessment, Issues, Improvement Proposals, and Checked Items.
• Brand Link Validity: Test each brand reference link in "6. Brand-specific notes" to ensure they navigate to the correct and active pages (Vercel, GitHub, OpenAI).
• Readability and Formatting: Review the entire document for clear English, correct heading hierarchy, and well-formatted lists and tables.

✨ Prompt for AI Agents

Use the following prompts with Cursor or Claude Code to automate E2E testing:

📝 E2E Test Generation Prompt

You are an expert QA engineer tasked with creating an automated test script in Node.js to validate a new Markdown documentation file for an AI agent. The file is located at `/.claude/agents/brand-guardian.md`.

The test script should verify the following:
1.  **File Existence**: The `brand-guardian.md` file exists at the specified path.
2.  **Document Structure**: The file contains all the required main headings:
    *   `# 🛡️ Brand Guardian – Logo Usage Reviewer`
    *   `## 1. Role`
    *   `## 2. Goals`
    *   `## 3. Principles`
    *   `## 4. Checklist`
    *   `## 5. Output format`
    *   `## 6. Brand-specific notes`
    *   `## 7. Tone`
3.  **Brand-Specific Notes**: The "Brand-specific notes" section includes subsections for `### Vercel`, `### GitHub`, and `### OpenAI`.
4.  **External Link Validity**: All specified external links are functional and return a `200 OK` status code. The links to check are:
    *   `https://vercel.com/design`
    *   `https://github.com/logos`
    *   `https://openai.com/brand`

**Implementation Requirements:**
*   Use Node.js.
*   Employ a testing framework like Jest for structuring tests and assertions.
*   Utilize the built-in `fs` module for file reading.
*   Use `axios` (install with `npm install -D axios`) for making HTTP requests to check link validity.
*   Ensure tests for link validation are run concurrently using `Promise.all` or `test.each`.
*   Provide clear error messages for any failures (e.g., missing file, missing heading, broken link).
*   The script should be organized into logical test suites and individual tests.
*   Assume the test script will be placed in a directory like `tests/documentation/brand-guardian.test.js` and needs to correctly resolve the path to `/.claude/agents/brand-guardian.md` (e.g., using `path.resolve`).

Generate the complete Node.js test script.

---

[shige]

Thank you!
I will add and revise this document later.