How this skill is triggered — by the user, by Claude, or both
Slash command
/claudster-extras:architecture-documentThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
```skill
---
name: architecture-document
context: fork
description: Generate professional enterprise-grade HLD and LLD documents from the living Architecture.md. Outputs DOCX (editable) or PPTX (executive summary) using existing document skills.
---
# Architecture Document Generator
Produce formal **High-Level Design (HLD)** and **Low-Level Design (LLD)** documents from the project's living `docs/Architecture.md` and codebase.
> **Project Context** — Read `project-config.md` for brand tokens, org name, tech stack, and project metadata used in document headers.
> **Document metadata** — Any Markdown companion doc or source doc created or updated in this workflow must follow `.github/instructions/document-frontmatter.instructions.md`. For DOCX/PPTX deliverables, mirror the same author/date/model fields on the cover page or revision history.
## When to Load This Skill
- Stakeholder requests a formal architecture deliverable
- Audit or compliance review requires documented HLD/LLD
- Onboarding pack for new team members
- Architecture review board submission
- Project milestone that requires design documentation
## Prerequisites
Before generating, ensure:
1. `docs/Architecture.md` exists and is current (the `@architect` agent maintains this)
2. Architecture diagrams exist in `docs/architecture/*.drawio` (or `.png` exports)
3. `project-config.md` has a profile set (for org name, tech stack, branding)
## Output Formats
| Format | Skill to Load | Best For |
|--------|---------------|----------|
| **DOCX** (recommended) | `.github/skills/document-skills/docx/SKILL.md` | Full HLD/LLD — editable, ToC, numbered sections |
| **PPTX** | `.github/skills/document-skills/pptx/SKILL.md` | Executive summary / architecture overview deck |
| **PDF** | `.github/skills/document-skills/pdf/SKILL.md` | Final read-only distribution (generate from DOCX) |
---
## HLD — High-Level Design
### Document Structure
COVER PAGE Project: <APP_TITLE> Organization: <ORG_NAME> Document Type: High-Level Design (HLD) Version: {from Architecture.md front-matter or git tag} Date: {current date} Author: {architect or team} Status: Draft | Under Review | Approved Classification: Internal | Confidential
REVISION HISTORY | Version | Date | Author | Changes |
APPROVAL TABLE | Role | Name | Signature | Date |
TABLE OF CONTENTS (auto-generated)
§1 INTRODUCTION §1.1 Purpose §1.2 Scope §1.3 Audience §1.4 References & Related Documents §1.5 Glossary & Abbreviations
§2 EXECUTIVE SUMMARY - Business context (1-2 paragraphs) - Solution overview (1-2 paragraphs) - Key architectural decisions summary
§3 SYSTEM CONTEXT §3.1 System Context Diagram (C4 Level 1) §3.2 External Systems & Interfaces §3.3 User Roles & Access Patterns §3.4 Data Sources
§4 ARCHITECTURE OVERVIEW §4.1 Architecture Style & Patterns §4.2 Component Architecture Diagram (C4 Level 2) §4.3 Component Descriptions (table: Component | Responsibility | Technology | Interfaces) §4.4 Technology Stack Summary
§5 DATA ARCHITECTURE §5.1 Data Flow Diagram §5.2 Data Sources & Stores §5.3 Data Integration Patterns §5.4 Data Retention & Archival
§6 INTEGRATION ARCHITECTURE §6.1 Integration Patterns (sync/async, push/pull) §6.2 API Overview (endpoints, protocols) §6.3 External System Interfaces §6.4 Message Flows / Event Flows
§7 DEPLOYMENT ARCHITECTURE §7.1 Deployment Diagram §7.2 Infrastructure Components §7.3 Environment Strategy (Dev/UAT/Prod) §7.4 Scaling & High Availability
§8 SECURITY ARCHITECTURE §8.1 Authentication & Authorization §8.2 Data Protection (at rest, in transit) §8.3 Network Security §8.4 Compliance Requirements
§9 NON-FUNCTIONAL REQUIREMENTS §9.1 Performance Targets §9.2 Availability & Reliability §9.3 Scalability §9.4 Maintainability §9.5 Observability (logging, monitoring, alerting)
§10 ARCHITECTURAL DECISIONS §10.1 Key Decisions Log (ADR summary table) §10.2 Alternatives Considered §10.3 Constraints & Trade-offs
§11 RISKS & MITIGATIONS (table: Risk | Likelihood | Impact | Mitigation)
§12 APPENDICES §A Full Diagram Index §B Glossary §C Referenced Documents
### Content Sourcing
| HLD Section | Source |
|-------------|--------|
| §1 Introduction | `project-config.md` (org, tech stack) + `README.md` |
| §2 Executive Summary | `docs/Architecture.md` introduction/overview |
| §3 System Context | `docs/Architecture.md` context sections + `docs/architecture/system-context.drawio` |
| §4 Architecture Overview | `docs/Architecture.md` component sections + diagrams |
| §5 Data Architecture | `docs/Architecture.md` data sections + `project-config.md` data sources |
| §6 Integration | `docs/Architecture.md` API/integration sections |
| §7 Deployment | `docs/Architecture.md` deployment sections + `project-config.md` deploy env |
| §8 Security | `docs/Architecture.md` security sections + `project-config.md` compliance |
| §9 NFRs | `docs/Architecture.md` NFR sections |
| §10 Decisions | `docs/architecture/` ADR files or decisions section |
| §11 Risks | `docs/Architecture.md` risks section (or flag if missing) |
---
## LLD — Low-Level Design
### Document Structure
COVER PAGE (same format as HLD, Document Type: Low-Level Design) REVISION HISTORY APPROVAL TABLE TABLE OF CONTENTS
§1 INTRODUCTION §1.1 Purpose §1.2 Scope (which HLD components this LLD covers) §1.3 HLD Reference (link to HLD document + version)
§2 MODULE DESIGN §2.1 Module Overview Diagram §2.2 Module Descriptions For each module: - Responsibility - Public interface (functions/methods/endpoints) - Dependencies (internal + external) - Configuration
§3 DATA MODEL §3.1 Entity Relationship Diagram §3.2 Table Definitions (table: Table | Columns | Types | Constraints | Indexes) §3.3 Data Validation Rules §3.4 Migration Strategy
§4 API DESIGN §4.1 API Endpoints (table: Method | Path | Request | Response | Auth | Rate Limit) §4.2 Request/Response Schemas (with examples) §4.3 Error Codes & Handling §4.4 Versioning Strategy
§5 SEQUENCE DIAGRAMS §5.1 Key User Flows (one sequence diagram per critical flow) §5.2 Error / Edge Case Flows §5.3 Background Process Flows
§6 CLASS / MODULE STRUCTURE §6.1 Package/Module Hierarchy §6.2 Key Classes & Responsibilities §6.3 Design Patterns Used §6.4 Dependency Injection / Configuration
§7 CACHING & STATE MANAGEMENT §7.1 Caching Strategy (table: Layer | Object | Strategy | TTL | Invalidation) §7.2 Session State Management §7.3 Serialization Constraints
§8 ERROR HANDLING & RESILIENCE §8.1 Error Classification §8.2 Retry Strategies §8.3 Circuit Breaker Patterns §8.4 Logging & Observability
§9 CONFIGURATION & ENVIRONMENT §9.1 Environment Variables §9.2 Feature Flags §9.3 Configuration Files §9.4 Secrets Management
§10 TESTING STRATEGY §10.1 Unit Test Approach §10.2 Integration Test Approach §10.3 E2E Test Scenarios §10.4 Performance Test Plan
§11 APPENDICES §A Full Class Diagram §B Database Schema DDL §C Sample API Payloads
### Content Sourcing
| LLD Section | Source |
|-------------|--------|
| §2 Module Design | Codebase scan (`src/` structure) + `docs/Architecture.md` |
| §3 Data Model | Database schema + `project-config.md` data sources |
| §4 API Design | FastAPI route inspection or API docs |
| §5 Sequence Diagrams | Generate from codebase call flows |
| §6 Class Structure | Codebase scan (imports, classes, modules) |
| §7 Caching | `docs/Architecture.md` caching sections + codebase |
| §8 Error Handling | Codebase patterns (try/catch, error types) |
| §9 Configuration | `.env.example`, `config.py`, `project-config.md` |
| §10 Testing | Test files + `docs/Architecture.md` testing strategy |
---
## Generation Workflow
### Step 1: Gather Sources
### Step 2: Determine Scope
Ask the user:
- **HLD, LLD, or both?**
- **Output format?** DOCX (recommended), PPTX (exec summary), or both?
- **Which components?** Full system or specific subsystem?
### Step 3: Assemble Content
Map each section to its source (see Content Sourcing tables above). For each section:
- If source content exists → extract and format
- If source is thin → flag with `[TODO: Expand — insufficient detail in Architecture.md]`
- If source is missing → flag with `[MISSING: No content found — update Architecture.md first]`
### Step 4: Generate Document
Load the appropriate document skill:
- **DOCX**: Load `.github/skills/document-skills/docx/SKILL.md` — use OOXML for professional formatting
- **PPTX**: Load `.github/skills/document-skills/pptx/SKILL.md` — use html2pptx workflow
### Step 5: Output
Save to:
- `docs/deliverables/HLD-{project-name}-v{version}.docx`
- `docs/deliverables/LLD-{project-name}-v{version}.docx`
- `docs/deliverables/Architecture-Overview-{project-name}-v{version}.pptx`
---
## Formatting Standards
### Enterprise Document Conventions
- **Font**: Arial or Calibri, 11pt body, 14pt headings
- **Section numbering**: §1, §1.1, §1.1.1 (three levels max)
- **Tables**: Bordered, header row shaded with brand primary color
- **Diagrams**: Captioned ("Figure N: Description"), referenced in text
- **Page headers**: Project name + Document type + "CONFIDENTIAL" (if applicable)
- **Page footers**: Page N of M + Version + Date
- **Line spacing**: 1.15 for body text
- **Margins**: 2.5cm all sides
### Diagram Embedding
For DOCX:
- Embed `.png` exports of `.drawio` diagrams
- Caption each figure: "Figure {N}: {Description}"
- Reference in text: "See Figure {N}"
For PPTX:
- One diagram per slide (full-width)
- Slide title = diagram caption
- Speaker notes = brief description
### Quality Checklist
Before delivering:
- [ ] Every section has content or explicit `[TODO]` marker
- [ ] All diagrams embedded and captioned
- [ ] Table of Contents generated and correct
- [ ] Revision history has current entry
- [ ] Cover page has correct project name, org, date
- [ ] No placeholder tokens (`<ORG_NAME>` etc.) remain — all resolved from project-config.md
- [ ] Section numbering is consistent and sequential
- [ ] Cross-references (e.g., "See §4.2") point to correct sections
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub saajunaid/junai --plugin claudster-extras