confluence-hla

Confluence High-Level Architecture (HLA) Authoring Skill

A cross-agent skill for Claude Code, OpenAI Codex CLI, and Antigravity (agy) to research systems, discover data pipelines, author enterprise-grade High-Level Architecture (HLA) documents, and export them directly into clean, self-contained Confluence Storage Format XHTML with native PlantUML macros.

1. Core Principles

1. Simplified Technical English (ASD-STE100 Style):
   • Short sentences (under 20 words where possible).
   • Active voice ("The worker queries telemetry" rather than "Telemetry is queried by the worker").
   • Clear, everyday technical words; one concept per sentence.
   • CRITICAL: Apply this style naturally. NEVER write notices, disclaimers, or metadata banners into the document stating that it was written in Simplified Technical English or ASD-STE100.
2. Zero AI Fingerprints, Zero Em-Dashes & Anti-Slop Discipline:
   • NEVER use em-dashes (—) or en-dashes (–): Em-dashes are the single most prominent dead giveaway of LLM-generated prose. Enterprise solutions architects do not write em-dashes. Use standard colons (:), hyphens (-), parentheses ((...)), or separate sentences instead.
     • Banned: High-Level Architecture (HLA) — AppointmentAssist
     • Required: High-Level Architecture (HLA): AppointmentAssist
     • Banned: - **Cancel Appointment — Area Outage:** ...
     • Required: - **Cancel Appointment (Area Outage):** ...
     • Banned: The system — which runs on Windows Server — polls telemetry.
     • Required: The system runs on Windows Server. It polls telemetry.
   • Absolute Ban on AI Slop Buzzwords and Hyperbolic Clichés:
     • Banned verbs & nouns: delve, tapestry, plethora, beacon, game-changer, testament, revolutionize, cornerstone, leverage (use use, read, or query), foster, streamline, harnessing, embark, landscape (in non-geographical contexts).
     • Banned adjectives: pivotal, crucial, meticulous, seamless, holistic, robust, comprehensive, cutting-edge, paramount, vibrant.
     • Banned transitions & framing: Furthermore, Moreover, In conclusion, It is important to note, Let's explore, Here is a breakdown:, Key takeaways:, Summary:.
   • Clean ASCII Punctuation:
     • Never use curly / smart quotes (“, ”, ‘, ’) — always use straight ASCII quotes (", ').
     • Never use unicode bullet symbols (•) — always use standard markdown hyphens (-).
     • Never use backtick formatting on ordinary English nouns.
   • Zero Meta-Commentary & Self-Referential Announcements:
     • Never write phrases announcing what the document is doing (e.g., "In this document we delve into...", "As requested by the user...").
     • Start immediately with the title, status, metadata block, and executive overview.
   • Zero Tool / Agent / Assistant / Model Self-Attribution:
     • The final Confluence export must NEVER contain YAML frontmatter, agent attribution tags, model names, preparation notices, or document references that expose internal repository paths or harness tooling (caddis, claude code, codex, antigravity, asd-ste100).
     • Note: Production application components (such as a local LLM daemon running on an on-premises GPU server) are documented as objective production system components, but the HLA itself must never attribute its own authorship to AI.
   • Automated Converter Enforcement:
     • The converter script (convert_hla_to_confluence.py) enforces this automatically by stripping all em-dashes, en-dashes, smart quotes, and AI buzzwords during HTML export.
3. Confluence Native Compatibility (Self-Contained PlantUML):
   • Uses native Confluence Storage Format XHTML.
   • All tables wrapped with <table class="wrapped"> and explicit <colgroup>.
   • Table of contents generated via <ac:structured-macro ac:name="toc" ac:schema-version="1"/>.
   • Pure PlantUML: Diagrams are rendered natively via Confluence PlantUML macros. No image uploads, attachments, or base64 data URIs are required—the generated HTML is 100% self-contained and ready for a single copy-paste into the Confluence Source Editor.
   • Guaranteed 100% valid XML parseable by the Confluence Source Editor.
4. Mermaid & PlantUML Full-Text Fidelity (Zero Truncation Rule):
   • In Markdown (.md), always wrap Mermaid text lines using explicit <br/> tags (maximum ~35 to 45 characters per line) across actors, notes, messages, node labels, and edge transitions.
   • Never allow unwrapped single-line strings to blow out diagram dimensions (>1200px) or truncate text in Git viewers, VS Code, or Confluence viewports.
   • The converter (convert_hla_to_confluence.py) dynamically maps <br/> to \n in PlantUML so that both formats render complete, untruncated text cleanly.