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

title: "[AI Ops] Spec and implementation plan for unified branding agent (headers, footers, badges)"
type: "AI Ops"
status: "needs-triage"
area: "infrastructure"
labels:

• "feature"
• "ai-ops:agents"
• "area:infrastructure"
• "documentation"
• "standards"
• "priority:important"
• "status:needs-triage"
  category: "agents"
  tags:
• "branding"
• "templates"
• "headers"
• "footers"
• "badges"
• "markdown"
• "accessibility"
• "schema-driven"
• "implementation-plan"
  owner: "lightspeedwp"
  repository: ".github"
  issue: 33
  children:
• "[AI Ops] Design footer/header/badge templates for unified branding agent #46"

AI Ops Summary

Define the specification, implementation plan, and delivery sequence for a unified branding agent that manages headers, footers, and badges across Markdown files in the repository.

This parent issue coordinates the full initiative: schema/config updates, template design, agent consolidation/refactor, documentation updates, implementation planning, and validation rules. It exists to ensure the branding system is delivered as a single modular workflow rather than a collection of disconnected rules and scripts.

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

Branding logic for Markdown files is currently fragmented across separate concepts, examples, and instructions. Header/footer behaviour, badge handling, and style guidance are related, but they are not yet defined as one coherent system.

That creates several problems:

• branding rules are spread across multiple files
• header/footer and badge concerns risk diverging over time
• template behaviour is not consistently tied to category or frontmatter
• schema/config does not yet fully model the intended behaviour
• implementation work could hard-code decisions that should live in config
• documentation and agent logic can drift apart

There is an opportunity to create a unified branding agent that:

• uses frontmatter and category/tag metadata as its source of truth
• applies category-aware headers, footers, and badges consistently
• keeps branding accessible, readable, and low-noise
• reduces maintenance cost by centralising rules
• makes future expansion easier without repeated refactors

Scope

In scope

• Define the unified branding agent purpose, boundaries, and responsibilities
• Define the category model for branded Markdown content
• Define the frontmatter and schema/config requirements
• Design header, footer, and badge template rules
• Decide how existing header/footer and badges logic should be merged
• Document implementation phases and task breakdown
• Update supporting docs and instructions as needed
• Define validation and success criteria for the final workflow

Out of scope

• Repository-wide retroactive application of branding to every existing Markdown file
• General documentation governance beyond branding-related needs
• Creating unrelated automation or tooling
• Restructuring the repo unless separately approved

Objectives

• Create one clear branding system for Markdown files
• Keep implementation modular and configuration-driven
• Minimise duplicated branding logic
• Keep templates accessible and readable
• Make category-based behaviour explicit
• Ensure implementation can be completed in small, reviewable steps

Proposed Deliverables

• Unified branding agent specification
• Implementation plan with phases and dependencies
• Category/tag model for Markdown branding
• Schema/config changes for category, tags, badges, and templates
• Template design outputs for headers, footers, and badges
• Documentation updates for usage and maintenance
• Validation guidance for accessibility and consistency

Child Issues / Workstreams

#46 — Template design

Design the header/footer/badge templates and document category-aware output rules.

Suggested additional child workstreams

These may remain checklist items here or be split into separate issues if needed:

• Schema/config update workstream
• Agent merge/refactor workstream
• Documentation update workstream
• Validation/testing workstream

Work Breakdown Structure

Phase 1 — Discovery and current-state audit

Review existing files, rules, and overlaps so the new branding system builds on what already exists instead of duplicating it.

Tasks:

• Review current related files and artefacts
  • footer-header-style.instructions.md
  • header-footer.agent.md
  • badges.agent.md
  • a11y.instructions.md
  • agent-config.schema.json
  • README.md
• Identify existing logic that should be retained
• Identify duplicated or overlapping responsibilities
• Identify any conflicting guidance or unclear ownership
• Confirm target directories and file categories in scope
• Confirm whether any current instruction files need consolidation or cross-linking

Outputs:

• Current-state inventory
• List of reusable rules/patterns
• List of gaps, conflicts, and decisions required

Phase 2 — Category and metadata model

Define how the branding system decides what to render.

Tasks:

• Confirm category list for Markdown branding
• Define intended use of category
• Define intended use of tags
• Determine whether path/folder context can supplement frontmatter
• Define precedence rules when category, tags, and path disagree
• Define defaults when frontmatter is missing
• Identify metadata needed for future extensibility without over-engineering

Outputs:

• Category model
• Metadata/frontmatter contract
• Precedence and fallback rules

Phase 3 — Template system design

This phase is primarily delivered by child issue #46.

Tasks:

• Define header rules by category
• Define footer rules by category
• Define badge rules by category
• Define template density and tone rules
• Define accessibility and readability constraints
• Produce example outputs for each supported category

Outputs:

• Category-to-template matrix
• Template rules
• Example outputs

Phase 4 — Schema/config design

Translate the branding rules into a configuration model that avoids hard-coded logic.

Tasks:

• Review current schema coverage
• Define schema fields for category and tags
• Define schema fields for badges
• Define schema fields for header/footer templates
• Decide what belongs in schema/config vs runtime agent logic
• Identify validation rules and required defaults

Outputs:

• Schema/config update plan
• Proposed agent-config.schema.json changes
• Validation requirements

Phase 5 — Agent architecture and implementation plan

Define how existing logic is merged into one agent with small, maintainable responsibilities.

Tasks:

• Confirm naming for the unified agent
• Define inputs and outputs for the agent
• Decide how header/footer and badge logic should be merged
• Identify reusable helper responsibilities
• Keep runtime logic minimal and config-driven
• Define safe rollout sequence to reduce regression risk

Outputs:

• Agent architecture notes
• Implementation sequence
• Refactor/merge plan

Phase 6 — Documentation and rollout guidance

Ensure maintainers understand how to use, extend, and review the system.

Tasks:

• Update or create branding documentation
• Update related instruction files
• Add cross-references where scope overlaps with a11y/docs/markdown guidance
• Document maintenance expectations
• Document reviewer guidance and success criteria

Outputs:

• Updated docs
• Reviewer guidance
• Maintenance notes

Parent Tracking Checklist

Planning

• Parent goal and scope agreed
• In-scope categories confirmed
• Child issues identified
• Dependencies mapped
• Implementation order agreed

Design

• Category model defined
• Frontmatter rules defined
• Template strategy defined
• Badge strategy defined
• Accessibility constraints defined

Technical design

• Schema/config approach defined
• Agent merge/refactor plan defined
• Runtime vs config responsibilities agreed
• Fallback behaviour defined

Delivery

• Documentation updates planned
• Validation/testing approach planned
• Follow-on implementation issues created or captured
• Reviewer/maintainer sign-off path clear

Acceptance Criteria

• The unified branding agent scope is clearly defined
• The branding system is broken into logical workstreams with clear ownership
• Category, frontmatter, and template requirements are documented
• Schema/config changes required for implementation are identified
• Agent merge/refactor direction is documented
• Documentation update requirements are identified
• Accessibility/readability constraints are captured
• Child issues or equivalent task breakdown exist for major workstreams
• The implementation plan supports small, reviewable PRs
• PR uses correct branch prefix (ai/)
• Approved by at least one maintainer

Success Metrics

• Maintainers can understand the full initiative without inferring missing steps
• Child issues map cleanly to implementation work
• Branding logic can be implemented from config/schema rather than hard-coded rules
• Documentation, schema, and agent behaviour stay aligned
• The final system is easier to maintain than the current split approach

Risks / Things to Avoid

• Combining too many concerns into one brittle agent
• Leaving template rules implied rather than explicit
• Over-designing the schema beyond current needs
• Letting decorative branding reduce readability
• Duplicating logic across docs, config, and runtime code
• Making the rollout so large that review becomes difficult

Dependencies

Parent dependencies

• Existing branding-related files and instructions
• Maintainer agreement on category model and branding constraints

Child dependencies

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

Enables

• Schema/config implementation work
• Unified agent implementation/refactor
• Clear documentation for future contributors

Additional Context

This issue is the parent planning and orchestration task for the unified branding agent initiative.

It should remain focused on:

• defining the system
• sequencing the work
• keeping the implementation modular
• reducing maintenance cost over time

Where practical, detailed execution should live in child issues so implementation can proceed in smaller, clearer PRs.

References

• Child issue: [AI Ops] Design footer/header/badge templates for unified branding agent #46
• 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
• Scope and workstreams defined
• Dependencies identified
• Acceptance criteria listed
• Child issue links added
• Estimate added

Definition of Done (DoD)

• All major workstreams are documented
• Child issues and sequencing are clear
• Implementation plan reviewed by maintainers
• Related docs/notes updated
• Follow-on implementation work is unblocked
• PR uses correct branch prefix (ai/)