[AI Ops] Schema update for unified branding agent (category, tags, badges) #49

name: "🧠 AI Ops"
about: "Propose, discuss, or troubleshoot AI/ML operations, workflows, or automation."
title: "[AI Ops] Create unified branding agent issue spec from #33"
labels: [status:needs-triage, area:ai, type:ai-ops]

AI Ops Summary

Define the schema and configuration model for the unified branding agent introduced in #33.

This issue covers the structured data layer required to support category-aware Markdown headers, footers, and badges across the LightSpeed .github repository. The goal is to provide a clear, maintainable and validation-friendly source of truth for category mapping, template selection, badge rules, and fallback behaviour.

This is a child issue of #33 and should stay focused on the schema/config model rather than template copywriting or agent implementation.

Parent issue:

• epic: branding-agent - Plan unified Markdown branding #33 — Unified branding agent parent specification

Related child issue:

• [AI Ops] Design footer/header/badge templates for unified branding agent #46 — Design footer/header/badge templates for unified branding agent

Problem / Opportunity

Issue #33 defines the broader branding-agent initiative, and issue #46 defines the template design layer. However, the implementation still needs a structured schema/config model that tells the agent:

• which document categories exist;
• how files are mapped to categories;
• which frontmatter fields are recognised;
• how tags influence badge or template behaviour;
• which header and footer template variants are valid per category;
• what fallback rules apply when metadata is missing or incomplete.

Without a clear schema/config layer, the branding agent is likely to become harder to validate, harder to extend, and more likely to accumulate hard-coded rules.

There is an opportunity to define a single, reviewable configuration model that:

• reduces duplication in agent logic;
• supports deterministic, testable output;
• keeps category and template behaviour visible to maintainers;
• provides a safe path for future category additions.

Approach / Solution

Define the schema/config layer for the unified branding agent so it can support repository-local Markdown branding in a structured and maintainable way.

The schema/config model should support:

• document category definitions;
• tags and optional subtype metadata;
• badge definitions and category-specific badge rules;
• header template references by category;
• footer template references by category;
• path-based defaults;
• frontmatter overrides;
• fallback behaviour for missing or invalid metadata;
• validation rules that fail safely and predictably.

Recommended configuration direction

Preferred approach:

• YAML authoring with JSON Schema validation

Rationale:

• YAML is easier for maintainers to read and update when managing category mappings and template references.
• JSON Schema provides strict validation without inventing new tooling or relying on undocumented conventions.
• This keeps configuration readable for humans and enforceable for automation.

Alternative options may be considered, but any deviation from this direction should be justified in terms of ROI, maintenance cost, and compatibility with the repo’s existing workflow.

Scope

In scope:

• schema/config structure for branding rules
• category definitions and controlled vocabulary
• frontmatter fields required or supported by the agent
• path-to-category mapping rules
• template reference structure
• badge rule structure
• validation expectations and failure behaviour
• maintainability guidance for future category additions

Out of scope:

• writing final header/footer copy variants
• designing the visual/content template matrix itself
• implementing the branding agent runtime logic
• unrelated documentation audits or repository restructuring

Required Schema / Config Capabilities

The schema/config design must support the following.

1. Category definitions

Support a controlled set of categories, including at minimum:

• issue
• pull-request
• docs
• ai-ops
• agents
• instructions
• prompts
• schema
• readme
• test
• utility
• awesome-copilot
• research
• audit
• workflow
• governance

Each category definition should allow for:

• identifier
• label/title
• description or purpose
• allowed badges
• allowed header templates
• allowed footer templates
• optional defaults
• fallback behaviour

2. Frontmatter field support

Define the frontmatter fields that the branding agent can consume, including at minimum:

• category
• tags

Consider whether additional optional fields are needed, such as:

• subtype
• status
• audience
• template
• badges

For each field, define:

• expected type
• required vs optional usage
• allowed values or patterns
• override behaviour
• validation expectations

3. Path-based defaults

Support path-aware defaults so files can still receive predictable branding when frontmatter is incomplete or absent.

Examples include mapping patterns such as:

• docs/** → docs
• instructions/** → instructions
• prompts/** → prompts
• agents/** → agents

The schema/config should document precedence between:

1. explicit frontmatter
2. path-based mapping
3. global defaults

4. Badge rules

Support a structured badge model that defines:

• badge identifiers
• label text
• optional category restrictions
• optional tag-driven activation
• placement rules
• ordering rules
• limits to prevent clutter

Badge handling should remain deterministic and maintainable.

5. Header and footer template references

The schema/config must support template references rather than forcing templates to be embedded directly into agent logic.

It should define:

• how categories reference header templates
• how categories reference footer templates
• whether multiple variants are allowed per category
• how a variant is selected
• whether selection is deterministic, configurable, or context-driven

6. Safe validation and failure behaviour

Define what happens when configuration is invalid or incomplete.

This should include:

• invalid category value
• unsupported tag
• unknown badge
• missing template reference
• malformed config
• missing required fields

The preferred behaviour should fail safely:

• avoid destructive edits;
• avoid guessing when uncertainty is high;
• provide predictable fallbacks where explicitly configured.

Relationship To Other Issues

This issue should remain aligned with:

• epic: branding-agent - Plan unified Markdown branding #33 — parent initiative, scope, governance, and required coverage
• [AI Ops] Design footer/header/badge templates for unified branding agent #46 — template design, footer/header/badge examples, and category-aware content patterns

Expected division of responsibility:

• epic: branding-agent - Plan unified Markdown branding #33 defines the parent initiative and category/footer requirements
• [AI Ops] Design footer/header/badge templates for unified branding agent #46 defines template design rules and examples
• [AI Ops] Schema update for unified branding agent (category, tags, badges) #49 defines the schema/config structure that makes those rules implementable

Deliverables

This issue should produce:

• a recommended config format decision
• a documented schema/config structure
• category and field definitions
• path/default precedence rules
• badge/template reference rules
• validation and failure-handling rules
• example config snippets sufficient to guide implementation
• documentation updates where needed

Acceptance Criteria

• The issue is clearly scoped as the schema/config layer for the unified branding agent
• Relationship to parent issue epic: branding-agent - Plan unified Markdown branding #33 is documented
• Relationship to template-design issue [AI Ops] Design footer/header/badge templates for unified branding agent #46 is documented
• Supported document categories are listed
• Schema/config support for category and tags is defined
• Optional supporting fields are identified or explicitly ruled out
• Path-based default mapping rules are documented
• Precedence between frontmatter, path rules, and defaults is documented
• Badge rule structure is documented
• Header/footer template reference structure is documented
• Validation rules and safe failure behaviour are documented
• Example config snippets are provided
• Accessibility and maintainability considerations are documented where relevant
• Documentation updated where needed
• PR uses correct branch prefix (ai/)
• Approved by at least one maintainer

Additional Context

This issue should make the implementation work smaller and safer by removing ambiguity from the configuration model before coding begins.

A maintainer should be able to read this issue and understand:

• what configuration format to use;
• what fields and categories are supported;
• how templates are referenced;
• how defaults and overrides work;
• how invalid config should be handled.

References

Parent issue:

• epic: branding-agent - Plan unified Markdown branding #33 — Unified branding agent parent specification

Related child issue:

• [AI Ops] Design footer/header/badge templates for unified branding agent #46 — Design footer/header/badge templates for unified branding agent

Related files:

• footer-header-style.instructions.md
• header-footer.agent.md
• badges.agent.md
• a11y.instructions.md
• agent-config.schema.json
• README.md

Definition of Ready (DoR)

• AI ops goal described
• Area/action mapped
• Acceptance criteria listed
• Estimate added

Definition of Done (DoD)

• All acceptance criteria met
• Schema/config model reviewed for maintainability and clarity
• Validation rules documented
• Documentation updated
• PR uses correct branch prefix (ai/)