generate-wiki

# Generate Wiki Skill **Role Definition**: You are a senior Java architect skilled in: - Analyzing code structure of gRPC + Java microservice projects - Understanding the mapping between proto definitions and Java implementations - Writing clear and accurate technical documentation - Identifying core business logic and key code paths Agent-driven workflow for generating consistent wiki documentation for gRPC + Java projects. ## What This Skill Does This skill does not parse source code through built-in project-specific scripts. Instead, it instructs the Agent to: - inspect the repository with code-search and file-reading tools - identify gRPC services, proto definitions, and Java implementations - generate a consistent wiki structure - follow the provided style and output requirements ## Important: Not a Generic Wiki Template **This skill provides a framework, not a one-size-fits-all solution.** Each project has unique characteristics that require targeted optimization: - **Different business domains** — e-commerce, fintech, logistics, etc. each have specific documentation needs - **Different architectures** — even within gRPC + Java, service patterns, middleware usage, and data flows vary - **Different team needs** — some teams need detailed API specs, others need high-level architecture overviews **You should customize the generated wiki based on:** 1. Your project's specific business logic and domain terminology 2. The actual service dependencies and data flows in your codebase 3. Your team's documentation standards and review requirements 4. The level of detail your developers need (API reference vs. architecture guide) The templates and structure provided are starting points — expect to refine them through multiple iterations with the Agent to match your project's specific needs. ## Required Workflow See [docs/workflow.md](docs/workflow.md) for the complete Agent workflow. ### Summary **Phase 1: Discovery** - Find all components first 1. **Scan** - Find ALL proto, PowerJob, and Pulsar files 2. **Inventory** - Record ALL services, methods, messages, jobs, consumers 3. **Output** - List complete component inventory before generating **Phase 2: Generate Component Pages** - Create detail documentation (with parallel optimization) 4. **Check Component Count** - If total components ≥ 50, enable parallel generation 5. **Generate** - Create wiki pages for ALL discovered components: - Every RPC method → `service/{Service}/{Method}.html` - Every PowerJob processor → `job/{JobClass}/execute.html` (if present) - Every Pulsar consumer → `consumer/{Consumer}/index.html` (merged structure) - **Parallel Strategy**: Different services/jobs/consumers can be generated in parallel - **Sequential Constraint**: Methods within same service are generated sequentially - **Note**: Consumers use merged structure (index.html only, no separate consume.html) **Phase 3: Generate Summary Pages (LAST)** - Aggregate from finalized generated content 5. **Re-read Generated Component Pages** - After all gRPC, PowerJob, and Pulsar pages are complete, re-read: - `service/**/index.html` and `service/**/*.html` - `job/index.html` and `job/*/index.html` (if present) - `consumer/index.html` and `consumer/*/index.html` (if present) - the component inventory manifest produced during Phase 1 6. **Generate System Architecture** (`01-system-architecture.html`) - Based on completed component pages, all discovered services, jobs, consumers, dependencies, and message flows 7. **Generate Core Features** (`02-core-features.html`) - Based on completed gRPC, PowerJob, and Pulsar component analysis, grouped into business capabilities 8. **Generate ER Diagram** (`03-er-diagram.html`) - Based on ALL proto message types plus completed service method request/response mappings 9. **Verify** - Run the quality checklist before finishing **Important**: System Architecture, Core Features, and ER Diagram MUST be generated AFTER all component pages are complete. They MUST re-read the completed component pages and component inventory manifest as the source of truth. Do not generate summary pages from memory, partial discovery results, or assumptions. ## Output Requirements ### Output Format Requirements **All generated pages must be rendered as HTML**, not raw markdown files. Generated structure: ``` wiki/ ├── index.html # Main navigation page (renders all content) ├── assets/ │ ├── css/style.css # Unified styling (includes collapsible nav styles) │ ├── js/nav-data.js # Navigation tree data (generated from components) │ └── js/nav.js # Dynamic navigation renderer ├── service/ # gRPC API documentation (always) │ └── ServiceName/ # One folder per gRPC service │ ├── index.html # Service overview page │ ├── MethodName.html # One HTML file per RPC method │ └── ... ├── job/ # PowerJob scheduled jobs (if used) │ └── JobClassName/ # One folder per PowerJob processor │ ├── index.html # Job overview page │ └── execute.html # Job execute method documentation ├── consumer/ # Pulsar consumers (if used) │ ├── index.html # Consumer overview page (list all consumers) │ └── ConsumerClassName/ # One folder per Pulsar consumer │ └── index.html # Consumer detail page (merged overview + method) ├── 01-system-architecture.html # System architecture (rendered HTML) - GENERATED LAST ├── 02-core-features.html # Core features (rendered HTML) - GENERATED LAST └── 03-er-diagram.html # ER diagram (rendered HTML) - GENERATED LAST ``` **Note**: - `job/` and `consumer/` directories are created only when the project actually uses PowerJob or Pulsar respectively. - **System Architecture, Core Features, and ER Diagram MUST be generated LAST** after all component pages are complete. - **Phase 3 source of truth**: before writing `01-system-architecture.html`, `02-core-features.html`, or `03-er-diagram.html`, the Agent MUST re-read all generated gRPC, PowerJob, and Pulsar pages plus the component inventory manifest. The summary pages are second-pass aggregation outputs, not first-pass guesses. - **nav-data.js must be regenerated** whenever components are added/removed/renamed. **Rendering approach** (choose one): 1. **Static HTML generation**: Convert each markdown template to complete HTML with styling 2. **SPA with router**: Single `index.html` that dynamically loads and renders markdown content If using approach #2 (SPA): - Only one `index.html` at root - Markdown files can be kept as `.md` but must be rendered in-browser - URL routing must work (e.g., `/#/service/UserService/GetUser`) **Important**: Users should never see raw markdown or download `.md` files when clicking links. ### Parallel Generation Strategy **When to use parallel generation:** ``` Total Components = gRPC Methods + PowerJob Processors + Pulsar Consumers If Total Components >= 50: → Enable SUBAGENT PARALLEL generation → Improves speed by 3-5x on large projects ``` **Independence Rules (What can be parallel):** | Component Type | Parallel Strategy | Constraint | |---------------|-------------------|------------| | gRPC Methods | Parallel across different services | Sequential within same service | | PowerJob Processors | Always parallel | Independent jobs | | Pulsar Consumers | Always parallel | Independent consumers | **Example Batch Strategy:** ``` # Batch 1 (Parallel) - ServiceA.GetUser - ServiceB.CreateOrder - ServiceC.UpdateInventory - OrderSyncJob - OrderEventConsumer # Batch 2 (Parallel) - ServiceA.ListUsers - ServiceB.CancelOrder - ServiceC.ListInventory - DataCleanJob - PaymentResultConsumer # ... continue until all components processed ``` **Subagent Implementation:** ```javascript // Determine if parallel generation is needed const totalComponents = grpcMethods.length + powerjobCount + pulsarCount; const useParallel = totalComponents >= 50; if (useParallel) { // Group independent components into batches const batches = createBatches(components); for (const batch of batches) { // Launch subagent for each component in batch const subagents = batch.map(component => Agent({ description: `Generate ${component.type} page: ${component.name}`, prompt: ` Generate wiki page for ${component.name} Type: ${component.type} Template: ${component.template} Metadata: ${JSON.stringify(component.metadata)} Save to: ${component.outputPath} ` }) ); // Wait for current batch to complete before next batch await Promise.all(subagents); } } else { // Sequential generation for small projects for (const component of components) { generatePage(component); } } ``` **Important:** - Always wait for ALL component pages to complete before Phase 3 (Summary Pages) - Subagents must use the same source link pattern and templates (auto-detect GitHub or GitLab from `git remote -v`) - Each subagent saves its output file independently ### Directory Grouping Rules #### gRPC Services Group RPC method documentation by **gRPC Service name**: - Each gRPC service gets its own subdirectory under `service/` - Directory name matches the service name in proto (e.g., `UserService/`) - All RPC methods belonging to the same service go into the same folder - Method file names match the RPC method name (e.g., `GetUser.html`) #### PowerJob Processors Group PowerJob documentation by **Job Processor class name**: - Each PowerJob processor gets its own subdirectory under `job/` - Directory name matches the processor class name (e.g., `OrderSyncJob/`) - Must identify: Job name, cron expression, processor class, execute method - Content should analyze: job purpose, scheduling logic, business implementation Example structure: ``` job/ ├── OrderSyncJob/ # Class: OrderSyncJob implements BasicProcessor │ └── index.html # Merged job page (overview + execute method details) └── DataCleanJob/ └── index.html # Merged job page ``` **Merged Structure**: Since each PowerJob processor implements BasicProcessor with only one `process()` method, the documentation uses a merged structure: - **Single `index.html`** contains both job overview and complete execute/process method details - **No separate `execute.html`** file - This reduces navigation depth and improves user experience, consistent with Pulsar consumer documentation #### Pulsar Consumers Group Pulsar consumer documentation by **Consumer class name**: - Each Pulsar consumer gets its own subdirectory under `consumer/` - Directory name matches the consumer class name (e.g., `OrderEventConsumer/`) - Must identify: Topic name, subscription name, consumer class, receive method - Content should analyze: message purpose, consumption logic, business handling Example structure: ``` consumer/ ├── index.html # Consumer overview page (lists all consumers with stats) ├── OrderEventConsumer/ # Class consuming order events │ └── index.html # Merged consumer page (overview + receive method) └── PaymentResultConsumer/ └── index.html # Merged consumer page ``` **Merged Structure**: Since each consumer typically has only one `receive()` method, the documentation uses a merged structure: - **Single `index.html`** contains both consumer overview and method details - **No separate `consume.html`** file - This reduces navigation depth and improves user experience ### Page Templates All component types follow consistent documentation templates: - [templates/page-service.md](templates/page-service.md) - gRPC service method documentation - [templates/page-powerjob.md](templates/page-powerjob.md) - PowerJob processor documentation - [templates/page-pulsar.md](templates/page-pulsar.md) - Pulsar consumer detail documentation - [templates/page-pulsar-overview.md](templates/page-pulsar-overview.md) - Pulsar consumer overview page (lists all consumers) - [templates/page-architecture.md](templates/page-architecture.md) - System architecture template - [templates/page-features.md](templates/page-features.md) - Core features template - [templates/page-er.md](templates/page-er.md) - ER diagram template with domain model and zoom/pan support ### Page Content Standards All pages follow a **fixed directory structure** for consistency: #### gRPC Service Overview Page Structure (index.html) The service overview page (index.html) provides a summary of the gRPC service with modern dashboard styling: **Required CSS Styles (inline in `<style>` tag)**: ```css /* Breadcrumb Navigation */ .breadcrumb { display: flex; align-items: center; gap: 8px; margin-bottom: 20px; font-size: 14px; color: var(--text-secondary); } .breadcrumb a { color: var(--primary-color); text-decoration: none; } .breadcrumb a:hover { text-decoration: underline; } .breadcrumb-separator { opacity: 0.5; } .breadcrumb-current { color: var(--text-primary); font-weight: 500; } /* Service Header with Gradient */ .service-header { display: flex; align-items: center; gap: 20px; margin-bottom: 30px; padding: 30px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 12px; color: white; box-shadow: 0 4px 20px rgba(102, 126, 234, 0.3); } .service-icon { font-size: 48px; opacity: 0.9; } .service-title h1 { font-size: 28px; margin-bottom: 8px; color: white; } .service-title p { font-size: 14px; opacity: 0.9; color: rgba(255, 255, 255, 0.9); } /* Stats Dashboard */ .stats-dashboard { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 16px; margin-bottom: 32px; } .stat-card { background: var(--card-bg); border-radius: 12px; padding: 24px; text-align: center; border: 1px solid var(--border-color); box-shadow: 0 2px 4px rgba(0, 0, 0, 0.05); transition: all 0.2s ease; } .stat-card:hover { transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); } .stat-card.primary { background: linear-gradient(135deg, #dbeafe 0%, #bfdbfe 100%); border-color: #93c5fd; } .stat-card.success { background: linear-gradient(135deg, #d1fae5 0%, #a7f3d0 100%); border-color: #6ee7b7; } .stat-card.warning { background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%); border-color: #fcd34d; } .stat-icon { font-size: 24px; margin-bottom: 8px; } .stat-value { font-size: 32px; font-weight: 700; line-height: 1; } .stat-card.primary .stat-value { color: #1e40af; } .stat-card.success .stat-value { color: #065f46; } .stat-card.warning .stat-value { color: #92400e; } .stat-label { font-size: 13px; color: var(--text-secondary); margin-top: 8px; } /* Method Table with Clickable Rows */ .method-table tr { cursor: pointer; transition: background-color 0.15s ease; } .method-table tr:hover { background-color: #eff6ff !important; } .method-table tr:hover td { color: var(--primary-color); } .method-table td:first-child { font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', 'Consolas', monospace; font-size: 13px; } /* Status Badge Improvements */ .badge { display: inline-flex; align-items: center; gap: 4px; padding: 4px 10px; border-radius: 12px; font-size: 12px; font-weight: 500; } .badge::before { content: ''; display: inline-block; width: 6px; height: 6px; border-radius: 50%; } .badge-success::before { background: var(--success-color); }