35 KiB
35 KiB
| description | allowed-tools |
|---|---|
| Generate comprehensive project documentation for engineers and non-engineers | Read, Write, Edit, Bash, Task, TodoWrite, Glob, Grep |
Eureka Index - Project Documentation Generator
Input: "$ARGUMENTS"
PURPOSE
Generate comprehensive, dual-audience documentation by analyzing the current project structure using parallel agent execution. The output is designed to be understandable for both engineers and non-engineers.
Documentation Layers
| Layer | Audience | Content |
|---|---|---|
| Executive Summary | Everyone | Project purpose, value, capabilities |
| Architecture Overview | Everyone | Visual diagrams, technology stack |
| Getting Started | Semi-technical | Setup, basic usage, configuration |
| Feature Guide | Non-engineers | Plain-language feature descriptions |
| API Reference | Engineers | Endpoints, schemas, authentication |
| Component Catalog | Engineers | Props, interfaces, usage examples |
| Data Models | Both | ER diagrams + plain descriptions |
| Glossary | Non-engineers | Technical terms explained |
EXECUTION ARCHITECTURE
┌─────────────────────────────────────────────────────────────────────┐
│ PARALLEL EXECUTION PIPELINE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 1: PARALLEL ANALYSIS (run_in_background: true) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Structure │ │ API │ │ Components │ │ Models │ │
│ │ Analyzer │ │ Analyzer │ │ Analyzer │ │ Analyzer │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ PHASE 2: SYNCHRONIZATION │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Merge & Create Unified Analysis │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ PHASE 3: PARALLEL DOCUMENTATION (run_in_background: true) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Main Doc │ │ API Docs │ │ Components │ │ Quick │ │
│ │ Generator │ │ Generator │ │ Generator │ │ Reference │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └─────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ PHASE 4: FINALIZATION │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ HTML Generation + Validation + Summary │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
⛔ CRITICAL RULES
MUST DO
- MUST launch analysis agents in parallel using
run_in_background: true - MUST wait for all analysis agents before synchronization
- MUST launch documentation agents in parallel after synchronization
- MUST include both technical and non-technical descriptions
- MUST validate generated documentation against actual code
CANNOT DO
- CANNOT make up features that don't exist
- CANNOT skip the parallel analysis phase
- CANNOT generate docs without synchronizing analysis results
EXECUTION FLOW
═══════════════════════════════════════════════════════════════
PHASE 1: Parallel Analysis
═══════════════════════════════════════════════════════════════
1.1: Display Start Banner & Setup
╔══════════════════════════════════════════════════════════════╗
║ 📚 EUREKA INDEX - Parallel Documentation Generator ║
╠══════════════════════════════════════════════════════════════╣
║ Launching parallel analysis agents... ║
║ Output: Dual-audience documentation (Engineer + Non-Engineer)║
╚══════════════════════════════════════════════════════════════╝
OUTPUT_DIR="${ARGUMENTS:-docs}"
mkdir -p "$OUTPUT_DIR"
echo "📁 Output directory: $OUTPUT_DIR"
1.2: Launch Parallel Analysis Agents
CRITICAL: Launch ALL four agents in a SINGLE message with multiple Task tool calls:
Launch these 4 Task agents IN PARALLEL (single message, multiple tool calls):
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 1: Structure Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # PROJECT STRUCTURE ANALYSIS │
│ │
│ Analyze the project structure and return findings. │
│ │
│ ## Tasks │
│ 1. Identify project type (package.json, requirements.txt, │
│ Cargo.toml, go.mod, pom.xml) │
│ 2. Extract metadata (name, version, description) │
│ 3. Map directory structure with purposes │
│ 4. Identify tech stack (language, framework, database) │
│ 5. List key dependencies with plain English purposes │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ project: │
│ name: "..." │
│ version: "..." │
│ description: "..." │
│ type: "node|python|rust|go|java|other" │
│ tech_stack: │
│ language: "..." │
│ framework: "..." │
│ database: "..." │
│ structure: │
│ directories: │
│ - path: "..." │
│ purpose: "..." │
│ file_count: N │
│ dependencies: │
│ - name: "..." │
│ purpose: "plain English" │
│ ``` │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 2: API Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # API ENDPOINTS ANALYSIS │
│ │
│ Find and analyze all API endpoints in the project. │
│ │
│ ## Search Patterns │
│ - Next.js App Router: app/api/**/route.ts │
│ - Next.js Pages: pages/api/**/*.ts │
│ - Express: router.get/post/put/delete │
│ - FastAPI: @app.get/post/put/delete │
│ - GraphQL: Query/Mutation resolvers │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ api_endpoints: │
│ - method: "GET|POST|PUT|DELETE" │
│ path: "/api/..." │
│ handler_file: "path/to/file.ts" │
│ description: "plain English" │
│ request_body: "schema if POST/PUT" │
│ response: "schema summary" │
│ auth_required: true|false │
│ ``` │
│ │
│ If no APIs found, return: api_endpoints: [] │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 3: Components Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # UI COMPONENTS ANALYSIS │
│ │
│ Find and analyze all UI components in the project. │
│ │
│ ## Search Patterns │
│ - React: components/**/*.tsx, function Component() │
│ - Vue: components/**/*.vue, <script setup> │
│ - Angular: *.component.ts, @Component │
│ - Svelte: **/*.svelte │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ components: │
│ - id: "component_name" │
│ name: "ComponentName" │
│ path: "path/to/Component.tsx" │
│ description: "what it does in plain English" │
│ props: │
│ - name: "propName" │
│ type: "string|number|boolean|..." │
│ required: true|false │
│ description: "what it controls" │
│ events: ["onClick", "onChange"] │
│ dependencies: ["OtherComponent"] │
│ ``` │
│ │
│ If no components found, return: components: [] │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ AGENT 4: Data Models Analyzer │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "Explore" │
│ run_in_background: true │
│ prompt: | │
│ # DATA MODELS ANALYSIS │
│ │
│ Find and analyze all data models in the project. │
│ │
│ ## Search Patterns │
│ - Prisma: prisma/schema.prisma, model X {} │
│ - TypeORM: @Entity(), entities/**/*.ts │
│ - Mongoose: new Schema(), models/**/*.ts │
│ - SQLAlchemy: class X(Base), models/**/*.py │
│ - TypeScript: interface/type definitions │
│ │
│ ## Output Format (YAML) │
│ ```yaml │
│ data_models: │
│ - name: "ModelName" │
│ source: "prisma|typeorm|mongoose|typescript" │
│ file_path: "path/to/model" │
│ description: "what data it represents" │
│ fields: │
│ - name: "fieldName" │
│ type: "String|Int|Boolean|..." │
│ description: "plain English" │
│ constraints: "unique|optional|default" │
│ relations: │
│ - type: "hasMany|belongsTo|hasOne" │
│ target: "OtherModel" │
│ glossary_terms: │
│ - term: "technical term found" │
│ definition: "plain English definition" │
│ ``` │
│ │
│ If no models found, return: data_models: [] │
└─────────────────────────────────────────────────────────────────┘
1.3: Wait for All Analysis Agents
Use TaskOutput tool to wait for each agent:
- TaskOutput with task_id from Agent 1, block: true
- TaskOutput with task_id from Agent 2, block: true
- TaskOutput with task_id from Agent 3, block: true
- TaskOutput with task_id from Agent 4, block: true
Collect all results for synchronization.
═══════════════════════════════════════════════════════════════
PHASE 2: Synchronization
═══════════════════════════════════════════════════════════════
2.1: Merge Analysis Results
Combine outputs from all 4 agents into a unified analysis:
# $OUTPUT_DIR/analysis.yml - Merged from parallel agents
project:
# From Agent 1: Structure Analyzer
name: "..."
version: "..."
description: "..."
type: "..."
tech_stack:
# From Agent 1: Structure Analyzer
language: "..."
framework: "..."
database: "..."
key_dependencies: [...]
structure:
# From Agent 1: Structure Analyzer
directories: [...]
api_endpoints:
# From Agent 2: API Analyzer
[...]
components:
# From Agent 3: Components Analyzer
[...]
data_models:
# From Agent 4: Data Models Analyzer
[...]
glossary_terms:
# Merged from all agents
[...]
2.2: Write Unified Analysis File
# Write merged analysis to file
Write the unified YAML to: $OUTPUT_DIR/analysis.yml
═══════════════════════════════════════════════════════════════
PHASE 3: Parallel Documentation Generation
═══════════════════════════════════════════════════════════════
3.1: Launch Parallel Documentation Agents
CRITICAL: Launch ALL four doc agents in a SINGLE message with multiple Task tool calls:
Launch these 4 Task agents IN PARALLEL (single message, multiple tool calls):
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 1: Main Documentation │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate PROJECT_DOCUMENTATION.md │
│ │
│ Using the analysis from $OUTPUT_DIR/analysis.yml, │
│ generate comprehensive main documentation. │
│ │
│ ## Sections Required │
│ 1. Executive Summary (plain English, no jargon) │
│ 2. Quick Start (installation, basic usage) │
│ 3. Architecture Overview (ASCII diagrams) │
│ 4. Features (dual-audience: plain + technical details) │
│ 5. Glossary (all technical terms explained) │
│ │
│ ## Rules │
│ - Plain English FIRST, technical in <details> tags │
│ - Include ASCII architecture diagrams │
│ - Use tables for structured data │
│ - Code blocks with language hints │
│ │
│ Write to: $OUTPUT_DIR/PROJECT_DOCUMENTATION.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 2: API Reference │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate API_REFERENCE.md │
│ │
│ Using api_endpoints from $OUTPUT_DIR/analysis.yml, │
│ generate detailed API documentation. │
│ │
│ ## Format per Endpoint │
│ ### [METHOD] /path │
│ **Description**: Plain English │
│ **Authentication**: Required/Optional │
│ │
│ <details> │
│ <summary>Technical Details</summary> │
│ Request body, response schema, example │
│ </details> │
│ │
│ If no APIs exist, write brief note explaining this. │
│ │
│ Write to: $OUTPUT_DIR/API_REFERENCE.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 3: Components Catalog │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate COMPONENTS.md │
│ │
│ Using components from $OUTPUT_DIR/analysis.yml, │
│ generate component catalog documentation. │
│ │
│ ## Format per Component │
│ ### ComponentName │
│ **Purpose**: Plain English description │
│ **Location**: `path/to/file` │
│ │
│ <details> │
│ <summary>Props & Usage</summary> │
│ Props table, usage example, dependencies │
│ </details> │
│ │
│ If no components exist, write brief note explaining this. │
│ │
│ Write to: $OUTPUT_DIR/COMPONENTS.md │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ DOC AGENT 4: Quick Reference │
├─────────────────────────────────────────────────────────────────┤
│ Task tool with: │
│ subagent_type: "technical-writer" │
│ run_in_background: true │
│ prompt: | │
│ # Generate QUICK_REFERENCE.md │
│ │
│ Using $OUTPUT_DIR/analysis.yml, create a one-page │
│ quick reference card. │
│ │
│ ## Sections (tables only, minimal text) │
│ - Commands (npm scripts, make targets) │
│ - Key Files (important files and purposes) │
│ - API Endpoints (method, path, purpose) │
│ - Environment Variables │
│ - Common Patterns │
│ │
│ Keep it to ONE PAGE - scannable, dense, useful. │
│ │
│ Write to: $OUTPUT_DIR/QUICK_REFERENCE.md │
└─────────────────────────────────────────────────────────────────┘
3.2: Wait for All Documentation Agents
Use TaskOutput tool to wait for each doc agent:
- TaskOutput with task_id from Doc Agent 1, block: true
- TaskOutput with task_id from Doc Agent 2, block: true
- TaskOutput with task_id from Doc Agent 3, block: true
- TaskOutput with task_id from Doc Agent 4, block: true
═══════════════════════════════════════════════════════════════
PHASE 4: Finalization
═══════════════════════════════════════════════════════════════
4.1: Generate HTML Documentation (Optional)
# If Python scripts exist, generate HTML
if [ -f "skills/documentation-generator/scripts/generate_html.py" ]; then
python3 skills/documentation-generator/scripts/generate_html.py \
$OUTPUT_DIR/analysis.yml \
skills/documentation-generator/templates/documentation.html \
$OUTPUT_DIR/index.html
fi
4.2: Validate Generated Documentation
Verify all documentation files exist and are non-empty:
$OUTPUT_DIR/analysis.yml$OUTPUT_DIR/PROJECT_DOCUMENTATION.md$OUTPUT_DIR/API_REFERENCE.md$OUTPUT_DIR/COMPONENTS.md$OUTPUT_DIR/QUICK_REFERENCE.md
4.3: Display Completion Banner
╔══════════════════════════════════════════════════════════════╗
║ ✅ PARALLEL DOCUMENTATION COMPLETE ║
╠══════════════════════════════════════════════════════════════╣
║ Execution: 4 analysis agents → sync → 4 doc agents ║
╠══════════════════════════════════════════════════════════════╣
║ Output Directory: $OUTPUT_DIR ║
╠══════════════════════════════════════════════════════════════╣
║ Files Created: ║
║ 📊 analysis.yml (Merged analysis data) ║
║ 📄 PROJECT_DOCUMENTATION.md (Main documentation) ║
║ 📄 API_REFERENCE.md (API details) ║
║ 📄 COMPONENTS.md (Component catalog) ║
║ 📄 QUICK_REFERENCE.md (One-page reference) ║
║ 🌐 index.html (HTML version - if generated) ║
╠══════════════════════════════════════════════════════════════╣
║ Performance: ║
║ ⚡ Analysis: 4 agents in parallel ║
║ ⚡ Documentation: 4 agents in parallel ║
║ ⚡ Total: ~2x faster than sequential execution ║
╚══════════════════════════════════════════════════════════════╝
ARGUMENTS
| Argument | Default | Description |
|---|---|---|
[output_dir] |
docs |
Output directory for documentation |
--format |
markdown |
Output format: markdown, html |
--sections |
all |
Sections to include: all, api, components, models |
--audience |
both |
Target: both, technical, non-technical |
EXAMPLES
# Generate full documentation with parallel agents
/eureka:index
# Generate in custom directory
/eureka:index my-docs
# Generate API-only documentation
/eureka:index --sections api
# Generate non-technical documentation only
/eureka:index --audience non-technical
PARALLEL EXECUTION BENEFITS
| Metric | Sequential | Parallel | Improvement |
|---|---|---|---|
| Analysis Phase | 4x agent time | 1x agent time | 75% faster |
| Doc Generation | 4x agent time | 1x agent time | 75% faster |
| Total Time | ~8 units | ~2 units | 4x faster |
DUAL-AUDIENCE WRITING GUIDELINES
For Non-Engineers (Primary)
- Lead with "What" and "Why", not "How"
- Use analogies and real-world comparisons
- Avoid acronyms; spell them out first time
- Use bullet points over paragraphs
- Include visual diagrams
For Engineers (Secondary)
- Include in collapsible
<details>sections - Provide code examples
- Reference file paths and line numbers
- Include type definitions
- Link to source files
Balance Example
## User Authentication
**What it does**: Allows users to securely log into the application
using their email and password.
**How it works** (simplified):
1. User enters credentials
2. System verifies them
3. User receives access
<details>
<summary>Technical Implementation</summary>
- **Strategy**: JWT-based authentication
- **Token Storage**: HTTP-only cookies
- **Session Duration**: 24 hours
- **Refresh Logic**: Automatic refresh 1 hour before expiry
**Key Files**:
- `src/auth/jwt.service.ts` - Token generation
- `src/auth/auth.guard.ts` - Route protection
</details>