docs-agent

Docs Agent Skill

Overview

The Docs Agent is responsible for maintaining accurate, up-to-date documentation across the Unite-Hub project:

1. README.md - Project overview, installation, usage
2. .claude/claude.md - System overview and configuration
3. .claude/agent.md - Agent definitions (canonical)
4. API Documentation - Endpoint references
5. Architecture Docs - System design documents
6. Changelog - Version history and release notes

Model Configuration

Model: claude-haiku-4-5-20251001 Reason: Fast, cost-effective, perfect for documentation tasks Cost: ~$0.10-0.20 per documentation update (vs $1-2 with Sonnet/Opus)

How to Use This Agent

Trigger

User says: "Update README", "Document new API endpoint", "Add changelog entry", "Sync docs with code"

What the Agent Does

1. Identify Documentation Need

Questions to Ask:

• What changed in the code?
• Which documentation files need updates?
• Is this a new feature, bug fix, or refactor?
• What's the target audience (developers, users, both)?

2. Read Current Documentation

Step A: Locate Documentation Files

# Find all markdown files
find . -name "*.md" | grep -v node_modules

Key Documentation Files:

• README.md - Main project README
• .claude/claude.md - System overview
• .claude/agent.md - Agent definitions
• ARCHITECTURE.md - System architecture
• API_DOCUMENTATION.md - API reference
• DEPLOYMENT_GUIDE.md - Deployment instructions
• *.md files in root (various guides)

Step B: Read Relevant Files

// Use text_editor tool
text_editor.view("README.md");
text_editor.view(".claude/claude.md");

3. Update Documentation

Step A: README.md Updates

README structure for Unite-Hub:

# Project Name

Brief description (1-2 sentences)

## Features

- Feature 1
- Feature 2
- Feature 3

## Tech Stack

### Frontend
- Next.js 16
- React 19
- Tailwind CSS

### Backend
- Supabase
- Next.js API Routes

### AI
- Claude Opus 4
- Claude Sonnet 4.5

## Installation

Step-by-step installation instructions

## Usage

How to use the application

## API Documentation

Link to API docs

## Deployment

Deployment instructions

## Contributing

How to contribute

## License

License information

Update Process:

1. Read current README
2. Identify outdated sections
3. Update relevant sections
4. Preserve structure
5. Maintain consistent tone

Step B: API Documentation Updates

When new API endpoint is created:

## API Endpoints

### POST /api/contacts/bulk-update

**Description**: Update multiple contacts in bulk

**Authentication**: Required (Supabase Auth)

**Request Body**:

{ "workspaceId": "uuid", "contactIds": ["uuid1", "uuid2"], "updates": { "status": "prospect", "tags": ["warm", "interested"] } }

**Response**:

{ "success": true, "updated": 2, "contacts": [...] }

**Errors**:
- `400` - Invalid input
- `401` - Unauthorized
- `500` - Server error

**Example**:

const res = await fetch("/api/contacts/bulk-update", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ workspaceId: "...", contactIds: ["..."], updates: { status: "prospect" } }) });

const data = await res.json();

Step C: .claude/claude.md Updates

After significant code changes:

1. Update "Current System Status" section:
2. Move fixed issues from "Critical Issues" to "Working Components"
3. Add new issues if discovered
4. Update component counts (e.g., "21 dashboard pages" → "22 dashboard pages")

1. Update "Tech Stack Details" section:
2. Add new dependencies
3. Update version numbers
4. Document new integrations

1. Update "Data Flow Analysis" section:
2. Add new workflows
3. Fix broken flows
4. Document critical break points

1. Update "Immediate Next Steps" section:
2. Remove completed tasks
3. Add new priority tasks
4. Re-prioritize remaining work

Step D: .claude/agent.md Updates

When agents change:

1. Add new agent definition:

```markdown ### 7. New Agent Name

ID: unite-hub.new-agent Model: claude-sonnet-4-5-20250929 Skill File: .claude/skills/new-agent/SKILL.md

#### Role What this agent does

#### Capabilities

• Capability 1
• Capability 2

#### Tools Available

• Tool 1
• Tool 2

#### When to Invoke

• Scenario 1
• Scenario 2

```

1. Update agent interaction patterns if workflows change

1. Update tool usage guidelines if new tools are added

4. Generate Changelog Entries

When code changes are released:

# Changelog

## [1.1.0] - 2025-11-16

### Added
- New bulk update API endpoint for contacts
- Dashboard analytics page
- Hot leads email send functionality

### Changed
- Updated README with new API documentation
- Improved workspace filtering across all pages

### Fixed
- Fixed missing workspace filter in dashboard overview
- Fixed undefined organization in AuthContext
- Fixed missing import in src/lib/db.ts

### Security
- Re-enabled authentication on all API routes
- Added RLS policies for new tables

Changelog Categories:

• Added: New features
• Changed: Changes to existing features
• Deprecated: Features that will be removed
• Removed: Removed features
• Fixed: Bug fixes
• Security: Security improvements

5. Update Architecture Diagrams

When system architecture changes:

Text-Based Diagrams (using Markdown):

## System Architecture

┌─────────────────┐ │ Next.js App │ │ (React 19 + │ │ App Router) │ └────────┬────────┘ │ ┌────┴────┐ │ │ ┌───▼───┐ ┌──▼─────────┐ │ API │ │ Dashboard │ │Routes │ │ Pages │ └───┬───┘ └────────────┘ │ ┌───▼────────────────┐ │ AI Agent Layer │ │ • Email Agent │ │ • Content Agent │ │ • Orchestrator │ └───┬────────────────┘ │ ┌───▼────────────────┐ │ Supabase Layer │ │ • PostgreSQL │ │ • Row Level Sec │ │ • Real-time Subs │ └────────────────────┘

Mermaid Diagrams (for complex flows):

## Data Flow

graph TD A[User Login] --> B[OAuth] B --> C[Supabase Auth] C --> D[Dashboard] D --> E[Load Contacts] E --> F[Display Hot Leads]

Common Tasks

Task 1: Document New API Endpoint

Steps:

1. Read the API route file (src/app/api/new-endpoint/route.ts)
2. Extract:
3. HTTP methods (GET, POST, etc.)
4. Request body schema
5. Response format
6. Error codes
7. Authentication requirements
8. Add to API_DOCUMENTATION.md
9. Update README if it's a major feature
10. Add example usage

Example Output:

### POST /api/agents/analyze

Analyze a contact using Claude AI to extract insights

**Request**:

{ "workspaceId": "uuid", "contactId": "uuid", "analysisType": "intelligence" | "sentiment" }

**Response**:

{ "success": true, "analysis": { "score": 85, "insights": "...", "recommendations": ["..."] } }

Task 2: Update README After Feature Launch

Steps:

1. Read current README
2. Add feature to "Features" section
3. Update "Tech Stack" if new dependencies
4. Add usage example if user-facing
5. Update screenshots if UI changed
6. Verify all links still work

Example Update:

## Features (UPDATED)

### 🤖 AI Intelligence Layer
- **Email Agent**: Automatically processes incoming emails, extracts intents, analyzes sentiment
- **Content Generator**: Creates personalized marketing content using Claude Opus 4 with Extended Thinking
- **Contact Intelligence**: AI-powered lead scoring (0-100) based on engagement, sentiment, and behavior
- **Orchestrator**: Coordinates multi-agent workflows for complex automation
- **NEW: Bulk Contact Analyzer**: Analyze multiple contacts simultaneously with Claude AI ✨

#