Custom Experts

Experts enable HAI Build Code Generator to deliver context-aware code generation tailored to specific technologies, frameworks, or domains. Create custom experts to encode your team’s best practices, coding standards, and institutional knowledge.

Overview

Experts provide:

Domain-specific guidelines: Tailored coding standards and best practices
Reference documentation: Up to 3 external documentation links
Context injection: Automatically loaded when relevant to the task
Reusable knowledge: Shared across team members

Built-in Experts

HAI Build includes four ready-to-use experts:

.NET: C# and .NET ecosystem best practices
Terraform: Infrastructure as Code guidelines
Node.js: JavaScript/TypeScript development standards
Go: Golang idioms and patterns

These are read-only and provide quick reference for common technologies.

Custom Expert Structure

Custom experts are stored in the .hai-experts folder:

.hai-experts/
└── my-expert-name/
    ├── metadata.json          # Expert configuration
    ├── prompt.md              # Guidelines (required)
    └── docs/                  # Reference documentation (optional)
        ├── doc-1.md
        ├── doc-2.md
        ├── doc-3.md
        └── status.json        # Processing status

metadata.json

Contains expert configuration:

{
  "name": "React Best Practices",
  "createdAt": "2024-01-15T10:30:00Z",
  "documentLinks": [
    "https://react.dev/learn",
    "https://react.dev/reference/react",
    "https://react-typescript-cheatsheet.netlify.app"
  ]
}

Fields:

name (required): Expert display name
createdAt (required): ISO timestamp
documentLinks (optional): Array of up to 3 URLs

prompt.md

Contains the expert’s guidelines (required):

# React Best Practices Expert

You are an expert in React and modern frontend development.

## Core Principles

1. **Functional Components**: Always use function components with hooks
2. **TypeScript**: Provide proper type definitions for all props and state
3. **Performance**: Optimize re-renders with useMemo, useCallback, and React.memo

## Code Structure

- Use named exports for components
- Keep components small and focused (< 200 lines)
- Extract custom hooks for reusable logic
- Use composition over inheritance

## Naming Conventions

- Components: PascalCase (e.g., UserProfile)
- Hooks: camelCase with 'use' prefix (e.g., useAuth)
- Props interfaces: ComponentNameProps (e.g., UserProfileProps)
- Event handlers: handle + EventName (e.g., handleClick)

## File Organization

components/ ├── Button/ │ ├── Button.tsx │ ├── Button.test.tsx │ ├── Button.styles.ts │ └── index.ts

## Example Component

```typescript
import React, { useState, useCallback } from 'react'

interface ButtonProps {
  label: string
  onClick: () => void
  variant?: 'primary' | 'secondary'
  disabled?: boolean
}

export const Button: React.FC<ButtonProps> = ({
  label,
  onClick,
  variant = 'primary',
  disabled = false
}) => {
  const handleClick = useCallback(() => {
    if (!disabled) {
      onClick()
    }
  }, [disabled, onClick])

  return (
    <button
      onClick={handleClick}
      disabled={disabled}
      className={`btn btn-${variant}`}
    >
      {label}
    </button>
  )
}

State Management

Use useState for local component state
Use useContext for shared state across few components
Use Redux Toolkit or Zustand for complex global state
Avoid prop drilling - use composition or context

Testing

Write tests using React Testing Library
Focus on user behavior, not implementation details
Aim for > 80% coverage
Test accessibility with jest-axe

Accessibility

Use semantic HTML elements
Include ARIA labels where needed
Ensure keyboard navigation works
Test with screen readers

### docs/ (Optional)

When document links are provided, HAI processes them into markdown files:

- **doc-1.md, doc-2.md, doc-3.md**: Processed documentation content
- **status.json**: Tracks processing status

```json
{
  "status": "completed",
  "processedAt": "2024-01-15T10:35:00Z",
  "documents": [
    { "url": "https://react.dev/learn", "processed": true },
    { "url": "https://react.dev/reference/react", "processed": true },
    { "url": "https://react-typescript-cheatsheet.netlify.app", "processed": true }
  ]
}

Creating a Custom Expert

Via VS Code Extension

Open the HAI Build sidebar
Navigate to the Experts section
Click “Create New Expert”
Fill in the required fields:
- Name: Expert display name (e.g., “FastAPI Best Practices”)
- Guidelines: Detailed coding standards and examples
- Document Links (optional): Up to 3 reference URLs
Click “Create”

HAI Build automatically:

Creates the folder structure in .hai-experts
Generates metadata.json and prompt.md
Processes document links (if provided)
Syncs the expert across workspace

Manual Creation

Create expert folder:

mkdir -p .hai-experts/fastapi-expert

Create metadata.json:

{
  "name": "FastAPI Best Practices",
  "createdAt": "2024-01-15T10:00:00Z",
  "documentLinks": [
    "https://fastapi.tiangolo.com/tutorial/"
  ]
}

Create prompt.md:

# FastAPI Expert

You are an expert in FastAPI and modern Python API development.

## Core Guidelines

1. Use Pydantic models for request/response validation
2. Implement proper dependency injection
3. Use async/await for I/O operations
4. Add comprehensive type hints

## Example Endpoint

```python
from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel
from typing import List

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str

@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int, db: Session = Depends(get_db)):
    user = await db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

4. HAI Build automatically detects and processes the expert on next startup

## Expert Guidelines Best Practices

### Structure

Organize guidelines into clear sections:

```markdown
# [Technology] Expert

## Overview
Brief description of the expert's domain

## Core Principles
Fundamental guidelines (3-5 key points)

## Code Structure
File organization and architecture patterns

## Naming Conventions
Consistent naming across the codebase

## Examples
Real code examples demonstrating best practices

## Common Patterns
Frequently used design patterns

## Anti-Patterns
What to avoid and why

## Testing
Testing strategies and examples

## Performance
Optimization guidelines

## Security
Security considerations and best practices

Content Guidelines

Be Specific: Provide concrete examples, not abstract advice
Show Code: Include real code snippets demonstrating patterns
Explain Why: Don’t just say what to do, explain the reasoning
Cover Edge Cases: Address common pitfalls and edge cases
Keep Updated: Review and update guidelines as frameworks evolve

Effective Examples

Good Example:

## Error Handling

Always use custom error classes for domain-specific errors:

```typescript
// Define custom error
export class ValidationError extends Error {
  constructor(public field: string, message: string) {
    super(`Validation failed for ${field}: ${message}`)
    this.name = 'ValidationError'
  }
}

// Use in code
function validateEmail(email: string): void {
  if (!email.includes('@')) {
    throw new ValidationError('email', 'Must contain @ symbol')
  }
}

// Handle in caller
try {
  validateEmail(userInput)
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Field error: ${error.field}`)
  }
}

**Poor Example:**

```markdown
## Error Handling

Use try-catch blocks to handle errors properly.

Reference Documentation

Adding Document Links

Provide up to 3 URLs to external documentation:

{
  "documentLinks": [
    "https://docs.framework.com/guide",
    "https://docs.framework.com/api",
    "https://github.com/framework/awesome-resources"
  ]
}

Best Link Types

Official Documentation: Framework guides and API references
Style Guides: Community-accepted coding standards
Best Practices: Curated resources and patterns

Processing Behavior

When links are provided:

HAI crawls each URL (up to 3 levels deep)
Extracts and converts content to markdown
Stores in docs/ folder
Updates status.json with progress

Processing runs asynchronously and doesn’t block expert creation.

Using Custom Experts

Automatic Context Loading

HAI automatically loads expert context when:

Files match the expert’s domain (e.g., .tsx files for React expert)
Task description mentions relevant keywords
Explicitly requested by the user

Manual Selection

Select an expert explicitly in the HAI interface:

Open HAI Build sidebar
Start a new task
Click “Select Expert”
Choose from available experts

Example Workflow

User: "Create a new React component for user authentication"

HAI: [Loads React Best Practices expert]
     [Applies guidelines from prompt.md]
     [References documentation from docs/]
     
     Creates component following:
     - TypeScript interfaces
     - Functional component pattern
     - Custom hooks for auth logic
     - Accessibility attributes
     - Comprehensive tests

Managing Experts

Updating Experts

Edit expert files directly:

# Edit guidelines
code .hai-experts/my-expert/prompt.md

# Update configuration
code .hai-experts/my-expert/metadata.json

HAI automatically syncs changes across the workspace.

Deleting Experts

Remove the expert folder:

rm -rf .hai-experts/my-expert

Or use the HAI interface:

Navigate to Experts section
Click delete icon on the expert
Confirm deletion

Commit .hai-experts to version control:

git add .hai-experts/
git commit -m "Add team coding experts"
git push

Team members automatically receive experts when they pull the repository.

Advanced Use Cases

Multi-Framework Experts

Create experts for full-stack scenarios:

# Full-Stack TypeScript Expert

## Frontend (React)
- Component patterns
- State management
- API integration

## Backend (Node.js + Express)
- Route structure
- Middleware patterns
- Error handling

## Database (PostgreSQL)
- Query optimization
- Migration patterns
- Type-safe queries with Prisma

## Integration Examples

[Include end-to-end examples]

Team-Specific Standards

Encode institutional knowledge:

# Company Backend Expert

## Internal Libraries

Always use our custom logger:

```typescript
import { Logger } from '@company/logger'

const logger = Logger.create('service-name')
logger.info('Operation started', { userId, action })

Deployment

Follow company CI/CD patterns:

Use .company.yaml for configuration
Run npm run build:prod before deploy
Tag releases with semantic versioning

Security

Use company SSO library for authentication
Encrypt sensitive data with @company/crypto
Log all security events to audit trail

### Migration Guides

Help with framework upgrades:

```markdown
# React 17 to 18 Migration Expert

## Automatic Batching

React 18 batches all state updates automatically.

**Before (React 17):**
```typescript
setTimeout(() => {
  setCount(c => c + 1)
  setFlag(f => !f)
  // Re-renders twice
}, 1000)

After (React 18):

setTimeout(() => {
  setCount(c => c + 1)
  setFlag(f => !f)
  // Re-renders once
}, 1000)

New Root API

Before:

import ReactDOM from 'react-dom'
ReactDOM.render(<App />, document.getElementById('root'))

After:

import { createRoot } from 'react-dom/client'
const root = createRoot(document.getElementById('root')!)
root.render(<App />)

## Examples

### Python/Django Expert

```markdown
# Django Best Practices Expert

## Project Structure

project/ ├── apps/ │ ├── users/ │ ├── posts/ │ └── common/ ├── config/ │ ├── settings/ │ │ ├── base.py │ │ ├── dev.py │ │ └── prod.py │ └── urls.py └── manage.py

## Models

Use abstract base models for common fields:

```python
from django.db import models
from django.utils import timezone

class TimestampedModel(models.Model):
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True

class Post(TimestampedModel):
    title = models.CharField(max_length=200)
    content = models.TextField()
    author = models.ForeignKey('users.User', on_delete=models.CASCADE)
    
    class Meta:
        ordering = ['-created_at']
        indexes = [
            models.Index(fields=['-created_at']),
        ]

Views

Use class-based views for CRUD operations:

from django.views.generic import ListView, CreateView
from django.contrib.auth.mixins import LoginRequiredMixin

class PostListView(LoginRequiredMixin, ListView):
    model = Post
    template_name = 'posts/list.html'
    context_object_name = 'posts'
    paginate_by = 20
    
    def get_queryset(self):
        return Post.objects.select_related('author').all()

### Kubernetes Expert

```markdown
# Kubernetes Deployment Expert

## Deployment Best Practices

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  labels:
    app: api-server
    version: v1
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
        version: v1
    spec:
      containers:
      - name: api
        image: myregistry/api:v1.0.0
        ports:
        - containerPort: 8080
          name: http
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5

## Troubleshooting

### Expert Not Loading

1. Check folder structure:
```bash
ls -la .hai-experts/my-expert/
# Should show metadata.json and prompt.md

Validate JSON syntax:

cat .hai-experts/my-expert/metadata.json | jq .

Restart HAI Build extension

Document Processing Failed

Check status.json for errors:

{
  "status": "failed",
  "error": "Network timeout",
  "documents": [
    { "url": "https://...", "processed": false, "error": "Timeout" }
  ]
}

Retry processing:

Delete docs/ folder
HAI will re-process on next usage

Next Steps

CLI Usage

Use HAI from the command line

COR-Matrix

Track AI code retention patterns

​Custom Experts

​Overview

​Built-in Experts

​Custom Expert Structure

​metadata.json

​prompt.md

​State Management

​Testing

​Accessibility

​Creating a Custom Expert

​Via VS Code Extension

​Manual Creation

​Content Guidelines

​Effective Examples

​Reference Documentation

​Adding Document Links

​Best Link Types

​Processing Behavior

​Using Custom Experts

​Automatic Context Loading

​Manual Selection

​Example Workflow

​Managing Experts

​Updating Experts

​Deleting Experts

​Sharing Experts

​Advanced Use Cases

​Multi-Framework Experts

​Team-Specific Standards

​Deployment

​Security

​New Root API

​Views

​Document Processing Failed

​Next Steps