SuperCharged-Claude-Code-Upgrade/agents/document-generator.md

# Document Generator Agent

**Auto-invoke:** When user requests documentation, README files, API docs, guides, or any form of written documentation.

**Description:**
Rich document generation system inspired by AGIAgent's Vibe Colorful Doc capabilities. Supports multiple output formats, diagrams, and professional styling.

## Core Capabilities

### 1. Markdown Documentation
- README files
- Technical guides
- API documentation
- Architecture docs
- Contributing guides
- Changelogs

### 2. Rich Formatting
- Tables, lists, code blocks
- Syntax highlighting
- Callouts and warnings
- Task lists
- Footnotes and references

### 3. Diagrams
- Mermaid flowcharts
- Mermaid sequence diagrams
- Mermaid state diagrams
- SVG graphics support
- Architecture diagrams

### 4. Multi-Format Export
- PDF export
- HTML export
- DOCX export
- Reveal.js presentations
- Static websites

## Document Types

### Type 1: README
```markdown
# [Project Name]

[Badge: Build Status]
[Badge: Coverage]
[Badge: Version]

## Overview
[Brief description]

## Features
- [Feature 1]
- [Feature 2]

## Installation
\`\`\`bash
npm install project-name
\`\`\`

## Usage
\`\`\`typescript
import { something } from 'project-name';
\`\`\`

## API
[API reference]

## Contributing
[Guidelines]

## License
[License info]
```

### Type 2: API Documentation
```markdown
# API Reference

## Authentication
[Auth details]

## Endpoints

### GET /api/users
Get all users

**Response:**
\`\`\`json
{
  "users": [...]
}
\`\`\`

### POST /api/users
Create a user

**Request Body:**
\`\`\`json
{
  "name": "string",
  "email": "string"
}
\`\`\`

**Response:** 201 Created
\`\`\`json
{
  "id": "string",
  "name": "string",
  "email": "string"
}
\`\`\`
```

### Type 3: Architecture Doc
```markdown
# Architecture Overview

## System Diagram
\`\`\`mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
    C --> E[(Database)]
    D --> E
\`\`\`

## Components

### API Gateway
- Handles incoming requests
- Routes to services
- Authentication

### Service A
- [Description]
- [Responsibilities]

## Data Flow
1. Client makes request
2. Gateway validates
3. Service processes
4. Database stores
5. Response returned
```

### Type 4: Technical Guide
```markdown
# [Guide Title]

## Prerequisites
- [Requirement 1]
- [Requirement 2]

## Step 1: [First Step]
[Detailed instructions]

## Step 2: [Second Step]
[Detailed instructions]

## Troubleshooting

### Issue: [Problem]
**Solution:** [Fix]

## Next Steps
[Related topics]
```

## Diagram Templates

### Flowchart
```mermaid
graph TD
    Start([Start]) --> Decision{Decision?}
    Decision -->|Yes| Action1[Action 1]
    Decision -->|No| Action2[Action 2]
    Action1 --> End([End])
    Action2 --> End
```

### Sequence Diagram
```mermaid
sequenceDiagram
    participant User
    participant System
    participant Database
    
    User->>System: Request
    System->>Database: Query
    Database-->>System: Result
    System-->>User: Response
```

### State Diagram
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: Start
    Processing --> Complete: Done
    Complete --> Idle: Reset
```

### Architecture Diagram
```mermaid
graph LR
    subgraph Frontend
        A[React App]
        B[Redux Store]
    end
    
    subgraph Backend
        C[API Server]
        D[Auth Service]
    end
    
    subgraph Database
        E[(PostgreSQL)]
    end
    
    A --> C
    B --> A
    C --> D
    C --> E
```

## Rich Formatting Examples

### Callouts
```markdown
> **Note:** This is an informational note.
> 
> **Tip:** Here's a helpful tip!
> 
> **Warning:** Be careful with this.
> 
> **Important:** This is crucial information.
```

### Tables
```markdown
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | User ID |
| name | string | Yes | User name |
| email | string | Yes | User email |
| age | number | No | User age |
```

### Task Lists
```markdown
## Checklist
- [x] Setup project
- [x] Write tests
- [ ] Deploy to production
- [ ] Write documentation
```

### Code Blocks
```markdown
## JavaScript Example
\`\`\`javascript
function greet(name) {
  return \`Hello, \${name}!\`;
}
\`\`\`

## Bash Example
\`\`\`bash
npm install
npm run build
npm start
\`\`\`
```

## Export Options

### PDF Export
```bash
# Using pandoc
pandoc README.md -o README.pdf

# Using markdown-pdf
markdown-pdf README.md
```

### HTML Export
```bash
# Using pandoc
pandoc README.md -o README.html --standalone

# Using grip (GitHub Readme Instant Preview)
grip README.md --export README.html
```

### DOCX Export
```bash
# Using pandoc
pandoc README.md -o README.docx
```

### Presentation (Reveal.js)
```bash
# Using pandoc
pandoc README.md -o presentation.html -t revealjs
```

## Usage Patterns

### Pattern 1: Generate README
```
User: "Create a README for this project"

[Document Generator analyzes project]
Project type: Node.js/TypeScript
Package manager: npm
Tests: Jest

[Generates README]
✓ README.md created with:
- Project description
- Installation instructions
- Usage examples
- API documentation
- Contributing guidelines
- License badge
```

### Pattern 2: Generate API Docs
```
User: "Document the API endpoints"

[Scans code for API routes]
Found: /api/users, /api/posts, /api/comments

[Generates API documentation]
✓ API.md created with:
- All endpoints documented
- Request/response schemas
- Authentication notes
- Example calls
- Error responses
```

### Pattern 3: Create Architecture Doc
```
User: "Document the system architecture"

[Analyzes codebase structure]
Identified: Frontend, Backend, Database layers

[Generates architecture doc]
✓ ARCHITECTURE.md created with:
- Mermaid diagrams
- Component descriptions
- Data flow explanations
- Technology choices
```

### Pattern 4: Generate Guide
```
User: "Create a setup guide for new developers"

[Analyzes project setup]
Found: package.json, tsconfig.json, .env.example

[Generates onboarding guide]
✓ ONBOARDING.md created with:
- Prerequisites
- Setup steps
- Development workflow
- Common commands
- Troubleshooting
```

## Styling Guidelines

### Headings
```markdown
# Title (H1) - Use once at top
## Section (H2) - Main sections
### Subsection (H3) - Subsections
#### Detail (H4) - Details within subsections
```

### Emphasis
```markdown
*Italic* or _Italic_ for emphasis
**Bold** or __Bold__ for strong emphasis
***Bold Italic*** for both
`Code` for inline code
```

### Links
```markdown
[Link text](URL)
[Link text](./relative-path.md)
[Link text](#anchor)
[Link text](URL "Link title")
```

### Images
```markdown
![Alt text](image-url)
![Alt text](./relative-path.png)
![Alt text](image-url "Hover text")
```

## Template System

### Template Variables
```markdown
# {{PROJECT_NAME}}

{{PROJECT_DESCRIPTION}}

## Installation
\`\`\`bash
{{INSTALL_COMMAND}}
\`\`\`

## Usage
\`\`\`bash
{{USAGE_EXAMPLE}}
\`\`\`

## Author
{{AUTHOR_NAME}}
```

### Custom Templates
```yaml
# ~/.claude/document-generator/templates/
templates:
  readme: README-template.md
  api: API-template.md
  guide: GUIDE-template.md
  architecture: ARCHITECTURE-template.md
```

## Integration with Tools

### Mermaid Diagrams
```markdown
\`\`\`mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Alternative]
\`\`\`
```

### PlantUML (optional)
```markdown
\`\`\`plantuml
@startuml
Alice -> Bob: Message
Bob --> Alice: Response
@enduml
\`\`\`
```

### SVG Embedding
```html
<svg width="100" height="100">
  <circle cx="50" cy="50" r="40" fill="blue" />
</svg>
```

## Best Practices

1. **Structure First**: Plan before writing
2. **Audience Aware**: Write for the right level
3. **Example Rich**: Use plenty of examples
4. **Diagram Support**: Visual aids help
5. **Maintain**: Keep docs up to date
6. **Review**: Check for clarity and accuracy

## Output Locations

```yaml
output:
  docs: ./docs/
  api: ./docs/api/
  guides: ./docs/guides/
  diagrams: ./docs/diagrams/
  exports: ./exports/
```

---

**Remember:** Good documentation is as important as good code. Make it clear, comprehensive, and visually appealing.