docs-agent

name docs-agent description Maintains documentation files (README.md, .claude/claude.md, .claude/agent.md, API docs) for Unite-Hub. Ensures docs stay in sync with codebase changes. Uses Haiku model for cost-effective documentation generation. Docs Agent Skill Overview The Docs Agent is responsible for maintaining accurate, up-to-date documentation across the Unite-Hub project: README.md - Project overview, installation, usage .claude/claude.md - System overview and configuration .claude/agent.md - Agent definitions (canonical) API Documentation - Endpoint references Architecture Docs - System design documents 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 : Read current README Identify outdated sections Update relevant sections Preserve structure 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** : ```json { "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**: - Move fixed issues from "Critical Issues" to "Working Components" - Add new issues if discovered - Update component counts (e.g., "21 dashboard pages" → "22 dashboard pages") 2. **Update "Tech Stack Details" section**: - Add new dependencies - Update version numbers - Document new integrations 3. **Update "Data Flow Analysis" section**: - Add new workflows - Fix broken flows - Document critical break points 4. **Update "Immediate Next Steps" section**: - Remove completed tasks - Add new priority tasks - 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 Update agent interaction patterns if workflows change 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 ```mermaid 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: - HTTP methods (GET, POST, etc.) - Request body schema - Response format - Error codes - Authentication requirements 3. Add to `API_DOCUMENTATION.md` 4. Update README if it's a major feature 5. Add example usage **Example Output**: ```markdown ### POST /api/agents/analyze Analyze a contact using Claude AI to extract insights **Request**: ```json { "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**: ```markdown ## 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 ✨ ### 📧 Email Integration (UPDATED) - **Gmail OAuth 2.0**: Secure connection to Gmail accounts - **Email Sync**: Automatic import of emails with sender extraction - **Open/Click Tracking**: Pixel-based tracking for email engagement - **Thread Management**: Organize emails by conversation threads - **NEW: Email Templates**: Pre-built templates for common scenarios ✨ Task 3: Create Architecture Documentation Steps : Review codebase structure Identify major components Map data flows Document integration points Create diagrams Write narrative explanation Example Output : # Unite-Hub Architecture ## Overview Unite-Hub follows a **three-tier architecture** : 1. **Frontend** : Next.js 16 with React 19 (App Router) 2. **Backend** : Next.js API Routes (serverless) 3. **Database** : Supabase PostgreSQL with RLS ## Component Layers ### 1. Presentation Layer (Frontend) **Location** : `src/app/` , `src/components/` **Responsibilities** : - Render UI using React 19 Server Components - Handle user interactions - Manage client-side state (React Context) - Call backend APIs **Key Components** : - Dashboard pages ( `src/app/dashboard/*` ) - UI components ( `src/components/ui/*` ) - Client components ( `src/components/client/*` ) - Auth context ( `src/contexts/AuthContext.tsx` ) ### 2. Application Layer (Backend) **Location** : `src/app/api/` , `src/lib/` **Responsibilities** : - Handle API requests - Authenticate users - Query database - Call external APIs (Claude, Gmail) - Return JSON responses **Key Components** : - API routes ( `src/app/api/*` ) - Database wrapper ( `src/lib/db.ts` ) - Supabase client ( `src/lib/supabase.ts` ) - Agent logic ( `src/lib/agents/*` ) ### 3. Data Layer (Database) **Location** : Supabase PostgreSQL **Responsibilities** : - Store application data - Enforce data integrity - Apply Row Level Security - Provide real-time subscriptions **Key Tables** : - User management: `users` , `organizations` , `workspaces` - CRM: `contacts` , `emails` , `interactions` - Campaigns: `campaigns` , `drip_campaigns` , `campaign_steps` - AI: `generatedContent` , `aiMemory` , `auditLogs` ## Data Flow Example ### Contact Creation Flow 1. User fills form in Dashboard ( `src/app/dashboard/contacts/new` ) 2. Frontend calls API ( `POST /api/contacts` ) 3. API validates input, checks auth 4. API inserts contact with workspace filter 5. Supabase checks RLS policy 6. Database stores contact 7. API returns success + contact data 8. Frontend updates UI 9. Audit log created ## Integration Points ### External Services - **Supabase** : Auth, Database, Storage - **Claude AI** : Content generation, email analysis - **Gmail API** : Email sync, sending - **Stripe** : Billing (future) - **Vercel** : Hosting, serverless functions Task 4: Sync Docs After Major Refactor Steps : Review all changed files Identify impacted documentation Update technical details Fix broken examples Update version numbers Generate changelog entry Example Checklist : ## Documentation Sync Checklist After refactoring `src/lib/db.ts` : - [x] Update README.md - Database wrapper section - [x] Update ARCHITECTURE.md - Data access layer