Skip to content

hlbpa-docs.md

Latest commit

 

History

History
84 lines (60 loc) · 5.16 KB

hlbpa-docs.md

File metadata and controls

84 lines (60 loc) · 5.16 KB

HLBPA Agent (High-Level Big-Picture Architect) ✨

View this agent and more in the awesome-copilot repository on GitHub.

Status: HLBPA Agent — Polish (purple badge)

NOTE: XML-supported agent versions have been removed to reduce maintenance. Use the Markdown-based custom agent format going forward.

Why Use HLBPA? ❓

  1. Rapidly understand complex repos.
  2. Auto‑generate API & data flow diagrams.
  3. Highlight missing tests or docs.
  4. Identify architectural gaps and risks.
  5. Get a visual overview of recent changes.

What Does HLBPA Actually Do? 🤔

HLBPA is your AI-powered architectural documentation assistant. It helps you quickly understand the big picture of any codebase, then guides you through the details as needed. Here’s what you can expect as a user:

  • Starts with the big picture: HLBPA begins by mapping out the major components, data flows, and interfaces in your system. You get a high-level overview first.
  • Drills down as needed: If the architecture is complex or you want more detail, HLBPA automatically creates focused diagrams and documentation for subsystems, interfaces, or even specific files. You can always ask it to narrow or expand the scope.
  • No code or tests generated: HLBPA is strictly for documentation. It won’t write code or tests—just docs, diagrams, and gap scans.
  • Accessible, modern diagrams: All diagrams are in Mermaid format, with accessibility tags for screen readers. Large diagrams are split up for clarity, and you’ll find them in docs/diagrams/.
  • Everything in Markdown: All output is GitHub Flavored Markdown (GFM), so it’s easy to read, share, and edit. Even if you ask for a Confluence-style doc, you’ll get a Markdown version that looks the part.
  • Iterative gap scan: HLBPA doesn’t stop at the first pass. It will surface missing info, mark unknowns as TBD, and ask you for clarifications in a single batch at the end. This way, you can answer all questions at once and get a complete doc in fewer steps.
  • You control the scope: By default, HLBPA documents the whole repo. But you can target a folder, subsystem, or file—just specify what you want. If you don’t, it will drill down as needed to make the architecture clear.
  • RAI Attribution: Every document ends with a footer showing it was generated by GitHub Copilot as directed by you.

How to Use HLBPA 🚀

How to Use 🪄

Example Prompt:

Please generate high-level documentation for this repo using the provided HLBPA agent. My name is Jane Doe. Artifact: architecture diagram and the test coverage gap report.

Artifact Types 🧩

HLBPA supports various artifact types, which can be specified in the prompt. Here are some common ones:

Artifact Type Description Default Diagram
doc Overview documentation flowchart
entity Entity relationship diagrams erDiagram
gapscan List of gaps in logic or documentation block
usecases User journey bullet points sequence
systems System architecture diagrams architecture
history Git commit history overview gitGraph

Tip

HLBPA always outputs diagrams in Mermaid format, with accessibility tags. Users can specify diagram types explicitly to override that selection.

How Diagrams Work:

  • Inline preferred: When large complex diagrams can be broken into smaller, digestible chunks
  • External files: When a large diagram cannot be reasonably broken down, making it easier to view when loading the page instead of trying to decipher text the size of an ant
  • Accessibility: Every Mermaid diagram provides alt text either via YAML front-matter (file mode) or accTitle: / accDescr: lines (inline).

Tip

For best results enable the following Mermaid rendering tools:

  • /hustcc/mcp-mermaid
  • vscode.mermaid-chat-features/renderMermaidDiagram
  • mermaidchart.vscode-mermaid-chart/mermaid-diagram-preview

Important

GitHub scope gotcha: The “MCP server in agent metadata” setup only wires itself up when the agent is stored at the org or enterprise level. If you’re using a personal agent, you’ll need to hook the MCP server up the old-fashioned way — configure it directly in your IDE settings, or in your repo’s Coding Agent config. Think of it as: org/enterprise agents get valet parking; personal agents park it yourself.

What You Get & How It Finishes

  • You’ll get at least one document and the diagrams you asked for (or that HLBPA thinks you need).
  • HLBPA will drill down to subsystems, interfaces, or files as needed to make the architecture clear—unless you tell it to stay high-level or focus on a specific area.
  • All docs are saved in Markdown under docs/, and diagrams in docs/diagrams/.
  • Any missing info is clearly marked as TBD and listed in a single “Information Requested” section at the end.
  • Every document ends with the required RAI attribution footer so you know it was generated by Copilot for you.

ChatGPT and GitHub Copilot helped me with clear ideas and straightforward solutions.