---
description: Generate comprehensive project documentation for engineers and non-engineers
allowed-tools: 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
1. **MUST** launch analysis agents in parallel using `run_in_background: true`
2. **MUST** wait for all analysis agents before synchronization
3. **MUST** launch documentation agents in parallel after synchronization
4. **MUST** include both technical and non-technical descriptions
5. **MUST** validate generated documentation against actual code

### CANNOT DO
1. **CANNOT** make up features that don't exist
2. **CANNOT** skip the parallel analysis phase
3. **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)║
╚══════════════════════════════════════════════════════════════╝
```

```bash
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:

```yaml
# $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

```bash
# 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)

```bash
# 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

```bash
# 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

```markdown
## 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>
```