Overview

Playbook 05: AI-Powered Presentation Slides & Technical Architecture Diagrams — Steering Instruction & Quality Standards

Playbook Track: 05 – Presentation Slides & Architecture Diagrams (Visual Systems, Claude Code & Antigravity Workflows)
Target Audience: Year 1 Computer Science & Software Engineering Students Domain Focus: Declarative Architecture Diagrams, C4 Modeling, Programmatic PPTX/Marp Slides, Claude Code & Antigravity Custom Skills, Automated Visual QA
Core Tooling Stack: Gemini 2.5 Pro & Flash, Claude 3.7 Sonnet (Claude Code CLI), Antigravity CLI (agy), Mermaid.js, PlantUML, D2, Structurizr (C4 DSL), python-pptx, Marp CLI, Model Context Protocol (MCP)
Delivery Format: Strict Markdown (.md) to GitHub origin/main
Tier 2 Export Rule: Word (.docx) or Google Docs will only be compiled upon user approval.
Live Schedule Tracker: PB-05 Chapter Schedule (Google Sheets)

1. Executive Mission & Visual Engineering Philosophy

In corporate IT and software engineering, vast amounts of engineering effort are squandered on manual visual documentation:

  • Architects spend hours wrestling with Visio, Lucidchart, or Draw.io, manually aligning boxes and arrows that immediately become obsolete as soon as code changes.
  • Technical leads spend entire weekends assembling 40-slide PowerPoint presentations for executive stakeholders, manually copying metrics, formatting bullet points, and struggling with inconsistent typography and color palettes.
  • Architecture diagrams lack formal ontology, blending network topology, container boundaries, and class methods into an unreadable "boxology" mess.

Playbook 05 introduces the Visual Engineering Revolution:

  1. From Manual Dragging to Diagramming-as-Code: Treating architectural diagrams like source code—version-controlled in Git, diffable, declaratively defined in domain-specific languages (Mermaid, PlantUML, D2, Structurizr), and compiled programmatically.
  2. From Manual Deck Crafting to Programmatic Slide Generation: Generating executive-ready PowerPoint (.pptx), PDF, and HTML slides from raw Markdown and structured JSON using python-pptx, Marp, and Slidev.
  3. From Isolated Work to Claude Code & Antigravity Automation: Leveraging Claude Code (with custom skills, slash commands, and MCP servers like mcp-server-drawio) and Antigravity CLI (with custom plugins and headless renderers) to autonomously extract system architectures from repositories and generate publication-grade slide decks.
  4. From Subjective Aesthetics to Automated Visual QA: Applying cognitive load theory, WCAG 2.1 AA color contrast validation, and multimodal vision models (Gemini 2.5 Pro, Claude 3.7 Sonnet Vision) to automatically critique and refine layout balance.

2. The 7 Universal Quality Acceptance Gates (Visual Systems & Slide Engineering)

Every chapter of Playbook 05 must satisfy all 7 universal quality gates before publication:

  1. Gate 1: Architectural Rigor & Declarative Precision:
    • Every chapter must formulate clear visual abstractions, declarative DSL specifications (Mermaid, D2, Structurizr, python-pptx), or mathematical layout coordinate geometry.
    • Include detailed Mermaid architectural diagrams, data flowcharts, or state machines.
    • Zero generic advice, fluff, or manual GUI screenshot tutorials.
  2. Gate 2: Mandatory Manual vs. Programmatic Contrasts:
    • Explicitly contrast the legacy manual WYSIWYG approach (manual box dragging, stale diagrams, copy-pasting text into PowerPoint) with modern Programmatic / Agentic engineering (GitOps diagram sync, declarative C4 ontology, automated slide compilation).
    • Provide structured comparative tables highlighting maintenance overhead, drift velocity, and reproducibility.
  3. Gate 3: Frontier AI Prompts, Claude Code & Antigravity Configurations:
    • Detail exact system instructions, temperature calibrations, and tool schemas for Gemini 2.5 Pro / Flash, Claude 3.7 Sonnet (Claude Code CLI), and Antigravity CLI (agy).
    • Provide concrete .claude/skills/ definitions, CLAUDE.md rules, MCP server tool schemas, and Antigravity custom plugin workflows.
  4. Gate 4: Quantitative Visual & Tooling Trade-Off Matrix:
    • Provide empirical benchmark matrices comparing diagram engines (Mermaid vs PlantUML vs D2 vs Structurizr) and slide engines (python-pptx vs Marp vs Slidev vs Reveal.js).
    • Evaluate compilation latency, styling flexibility, C4 compliance, version-control diffability, and executive readiness.
  5. Gate 5: The 10 Methodological Threats to Validity & Visual Anti-Patterns:
    • Analyze 10 critical visual and architectural anti-patterns (e.g., "Boxology" ambiguity, cognitive load saturation, unreadable text scaling, color contrast violations, semantic diagram drift, cyclic spaghetti layouts, font embedding corruption).
    • Provide concrete programmatic defense mechanisms and automated linting guardrails for each.
  6. Gate 6: Mandatory Hands-On Lab (Visual Engineering Simulation):
    • Provide a step-by-step, actionable visual engineering challenge allowing Year 1 students to run diagram linting, slide generation, or layout validation directly on their machine.
  7. Gate 7: Mandatory Recommended Answer & Executable Solution:
    • Provide a fully tested, runnable zero-dependency Python 3.11+ script implementing the diagram parser, layout geometry calculator, or slide compiler.
    • Must contain built-in unit test assertions certifying 100% functional and mathematical compliance.
    • Must execute cleanly and emit green assertion outputs.

3. Master 8-Chapter Syllabus + Appendices

Chapter Title Technical Scope & Visual Engineering Focus Hands-On Lab (Gate 6) Recommended Solution (Gate 7)
Ch 01 The Visual Communication & Declarative Diagramming Shift Dual-Coding Theory, Cognitive Load Theory, visual hierarchy, moving from manual WYSIWYG to Declarative Diagramming-as-Code. Declarative Diagram AST & Syntactic Linter Python 3.11+ AST validator parsing diagram DSL tokens and verifying structural integrity.
Ch 02 Architecture Diagramming-as-Code (Mermaid, PlantUML & D2) Deep comparative mechanics of Mermaid, PlantUML, and D2; subgraphs, sequence flows, state diagrams, cloud topologies, styling. Multi-Engine Diagram Generator & Cross-Syntax Transpiler Python engine converting generic graph definitions into Mermaid and D2 syntax with layout validations.
Ch 03 C4 Model Visual Ontology & Structurizr Automation The C4 Model (Context, Container, Component, Code), Structurizr DSL, automated codebase architecture extraction, ADR diagramming. C4 Hierarchy Validator & Consistency Verifier Python engine validating C4 hierarchy levels and preventing cross-boundary leakage.
Ch 04 Programmatic Slide Generation with Python-PPTX & Marp Programmatic PowerPoint (.pptx) creation, slide master inheritance, shape coordinate geometry, Marp Markdown-to-Presentation compiler. Programmatic PPTX Slide Generator & Layout Geometry Engine Python engine calculating millimeter-accurate 16:9 layout coordinates and rendering structured slide decks.
Ch 05 Claude Code & Antigravity CLI Workflows, Skills & Plugins Building custom skills for Claude Code (CLAUDE.md, .claude/skills/), Antigravity plugins, Draw.io/Mermaid MCP tools, headless pipelines. Agentic Slide & Diagram Workflow Orchestrator Python engine simulating Claude Code / Antigravity skill dispatching for automated diagram generation.
Ch 06 Multimodal Vision Critique & Visual Quality Assurance Automated aesthetic auditing, WCAG 2.1 AA contrast ratio checks, text-overlap collision detection, cognitive density scoring. Multimodal Visual Density & Contrast Auditor Python engine calculating luminance contrast ratios, detecting bounding-box collisions, and scoring density.
Ch 07 End-to-End Enterprise Deck & Architecture Brief Automation Full autonomous pipeline: Git Repo / PRD -> Architecture Extraction -> C4 Container Diagram -> 10-Slide Executive Deck (.pptx & PDF). Full Autonomous Repo-to-Deck Compiler End-to-end Python pipeline transforming codebase architecture into a validated slide presentation.
Ch 08 Curated GitHub Ecosystem & Open-Source Tooling Suite Comprehensive comparative evaluation of 30+ top-tier open-source repositories: Mermaid, D2, Structurizr, python-pptx, Marp, Slidev, Draw.io. Open-Source Tooling Benchmark & Feature Matrix Evaluator Python engine scoring and ranking visual engineering tools across 6 enterprise capability dimensions.
App A Master System Prompts, Design Tokens & Presentation Schemas Production prompt library for Visual Architect agents, design token color palettes, typography rules, slide JSON schemas. Reference Prompts, Schemas & Tokens Complete configuration library and operational templates.
App B CLI Runbooks & Claude Code / Antigravity Setup Guides Step-by-step CLI runbooks for MCP servers (drawio, mermaid), Marp CLI, D2, headless Chromium, and agy plugins. Operational Runbooks & Setup Guides Production installation scripts and headless rendering pipelines.

4. Execution Rules & Delivery Cadence

  1. Markdown First: All documents published in .md format to playbooks/05-slides-and-diagrams/.
  2. Continuous Pushing: Commit and push at natural checkpoints to origin/main.
  3. Live Google Sheets Tracking: Maintained in PB-05 Chapter Schedule (Sheet ID 1909822231) and Playbook Catalog.
  4. Approval Gate for Word Export: Word (.docx) or Google Docs export remains strictly paused until explicit approval is granted.