← back to Designer Wallcoverings

DW-Agents/dw-agents/chat-logs/HOOK-INTEGRATION-RULES.md

366 lines

# Hook Integration Rules - ALWAYS FOLLOW

**Created:** 2025-11-12
**Rule:** Every hook must be accessible via buttons in agent dashboards
**Authority:** User directive - MANDATORY

---

## 🎯 Core Principle

**EVERY HOOK = BUTTON + SERVICE**

When creating or updating hooks, ALWAYS provide:
1. **Button** - UI element in agent dashboards
2. **Service** - Backend endpoint to trigger the hook
3. **Documentation** - Clear usage instructions

---

## 📋 Implementation Checklist

For EVERY new hook, you MUST:

### 1. Create the Hook File
```bash
/root/DW-MCP/DW-Hooks/[hook-name].js
```

### 2. Add Button to Agent Dashboards
**Location:** Each agent's HTML dashboard file

**Button Template:**
```html
<button onclick="triggerHook('[hook-name]')" class="hook-button">
  🔧 [Hook Display Name]
</button>
```

### 3. Create API Endpoint
**Location:** Agent's server file or shared API

**Endpoint Template:**
```javascript
app.post('/api/hooks/[hook-name]', async (req, res) => {
  try {
    const { exec } = require('child_process');
    exec('node /root/DW-MCP/DW-Hooks/[hook-name].js', (error, stdout, stderr) => {
      if (error) {
        return res.status(500).json({ error: stderr });
      }
      res.json({ success: true, output: stdout });
    });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});
```

### 4. Add to Hook Registry
**Location:** `/root/DW-MCP/DW-Hooks/README.md`

Update the hooks list with:
- Hook name
- Purpose
- Which agents have buttons
- Example usage

---

## 🎨 Button Placement Strategy

### Primary Dashboard Section
Place most-used hooks in the main dashboard area:
```html
<div class="hooks-panel">
  <h3>🔧 Quick Actions</h3>
  <div class="button-grid">
    <button onclick="runHealthCheck()">🏥 Health Check</button>
    <button onclick="fixServices()">🔧 Auto-Fix</button>
    <button onclick="viewLogs()">📋 View Logs</button>
  </div>
</div>
```

### Settings/Tools Section
Place admin hooks in a dedicated section:
```html
<div class="admin-tools">
  <h3>⚙️ Admin Tools</h3>
  <button onclick="runHook('service-health-check')">Check All Services</button>
  <button onclick="runHook('inter-agent-chat')">Test Chat System</button>
  <button onclick="runHook('product-import-pipeline')">Run Import</button>
</div>
```

### Context-Specific
Some hooks are agent-specific:
- **Marketing Agent:** Social media hooks, campaign tools
- **Legal Team:** Compliance checkers, settlement review
- **Shopify Store:** Product updates, inventory sync

---

## 📊 Hook Categories & Button Locations

### System Hooks (All Agents)
- **service-health-check-hook.js** → All dashboards, top-right
- **agent-health-monitor-hook.js** → Master Hub, sidebar
- **error-notification-hook.js** → All dashboards, alert section

### Communication Hooks (Relevant Agents)
- **gmail-hook.js** → Marketing, Legal, CEO dashboards
- **slack-hook.js** → All executive dashboards
- **twilio-hook.js** → Customer support agents
- **inter-agent-chat-hook.js** → All agents, chat widget

### Workflow Hooks (Specific Agents)
- **order-processing-hook.js** → Shopify Store dashboard
- **product-import-pipeline-hook.js** → Purchasing, Marketing
- **shopify-hook.js** → Shopify Store, Purchasing
- **calendar-hook.js** → CEO, COO, scheduling tools

### Monitoring Hooks (Master Hub + Executives)
- **mcp-server-startup-hook.js** → Master Hub
- **post-deployment-health-check.js** → Master Hub, DevOps
- **chat-verification-and-logging-hook.js** → Chat dashboard

---

## 🔄 Standard Hook Integration Pattern

### Step 1: Hook File Structure
```javascript
#!/usr/bin/env node
/**
 * [Hook Name]
 *
 * Purpose: [What it does]
 * Used by: [Which agents]
 *
 * CLI Usage:
 *   node [hook-name].js [command] [args]
 *
 * API Usage:
 *   POST /api/hooks/[hook-name]
 *   Body: { command: 'action', params: {...} }
 */

// Hook implementation...

// Export for API use
module.exports = { mainFunction, helperFunction };
```

### Step 2: Agent Dashboard Integration
```html
<!-- In agent's HTML file -->
<script>
async function runHook(hookName, params = {}) {
  const response = await fetch(`/api/hooks/${hookName}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(params)
  });

  const result = await response.json();

  if (result.success) {
    showNotification('Success!', result.output);
  } else {
    showNotification('Error!', result.error, 'error');
  }
}

function showNotification(title, message, type = 'success') {
  // Notification UI implementation
}
</script>

<!-- Buttons -->
<div class="hooks-section">
  <button onclick="runHook('health-check')">🏥 Health Check</button>
  <button onclick="runHook('auto-fix')">🔧 Auto-Fix</button>
</div>
```

### Step 3: API Endpoint
```javascript
// In agent's server file
const express = require('express');
const { exec } = require('child_process');
const path = require('path');

app.post('/api/hooks/:hookName', async (req, res) => {
  const { hookName } = req.params;
  const params = req.body;

  const hookPath = path.join('/root/DW-MCP/DW-Hooks', `${hookName}.js`);

  // Build command with params
  const args = Object.entries(params).map(([k, v]) => `${k}=${v}`).join(' ');
  const command = `node ${hookPath} ${args}`;

  exec(command, (error, stdout, stderr) => {
    if (error) {
      return res.status(500).json({
        success: false,
        error: stderr || error.message
      });
    }

    res.json({
      success: true,
      output: stdout,
      timestamp: new Date().toISOString()
    });
  });
});
```

---

## 📝 Current Hooks Needing Buttons

### ✅ Already Have Buttons
(None yet - this is the new standard!)

### ⚠️ Need Button Integration

1. **service-health-check-hook.js**
   - Add to: All agent dashboards
   - Button: "🏥 Check Services"
   - Location: Tools section

2. **inter-agent-chat-hook.js**
   - Add to: All agent dashboards (already has chat widget)
   - Button: "💬 Chat Commands"
   - Location: Chat widget settings

3. **gmail-hook.js**
   - Add to: Marketing, Legal, Executive agents
   - Button: "📧 Send Email"
   - Location: Communication panel

4. **twilio-hook.js**
   - Add to: Customer support agents
   - Button: "📱 Send SMS"
   - Location: Communication panel

5. **slack-hook.js**
   - Add to: All executive dashboards
   - Button: "💬 Post to Slack"
   - Location: Communication panel

6. **product-import-pipeline-hook.js**
   - Add to: Purchasing, Shopify Store
   - Button: "📦 Import Product"
   - Location: Primary actions

7. **agent-health-monitor-hook.js**
   - Add to: Master Hub
   - Button: "👥 Monitor Agents"
   - Location: System panel

8. **error-notification-hook.js**
   - Add to: All dashboards
   - Button: "🚨 Test Alerts"
   - Location: Settings/testing

9. **order-processing-hook.js**
   - Add to: Shopify Store
   - Button: "🛒 Process Orders"
   - Location: Primary actions

10. **shopify-hook.js**
    - Add to: Shopify Store, Marketing
    - Button: "🏪 Shopify Actions"
    - Location: Primary actions

---

## 🎯 Implementation Priority

### Phase 1: Critical Hooks (Do First)
1. service-health-check-hook.js → All agents
2. inter-agent-chat-hook.js → All agents
3. agent-health-monitor-hook.js → Master Hub

### Phase 2: Communication Hooks
4. gmail-hook.js → Marketing, Legal, Executives
5. slack-hook.js → Executives
6. twilio-hook.js → Support agents

### Phase 3: Workflow Hooks
7. product-import-pipeline-hook.js → Purchasing, Shopify
8. order-processing-hook.js → Shopify Store
9. shopify-hook.js → Shopify Store, Marketing

### Phase 4: Monitoring & Testing
10. error-notification-hook.js → All agents
11. All remaining hooks

---

## 💡 Best Practices

### Button Design
- **Emoji first** for visual recognition
- **Clear action verbs** (Check, Fix, Send, Run)
- **Consistent styling** across all agents
- **Loading states** while hook executes
- **Success/error feedback** after completion

### Hook Naming
- **Descriptive:** `service-health-check` not `check`
- **Consistent:** Always use kebab-case
- **Namespaced:** Group related hooks (`gmail-`, `slack-`, etc.)

### Error Handling
- Always provide meaningful error messages
- Log all hook executions
- Implement timeout protection
- Show user-friendly errors in UI

### Documentation
- Every hook MUST have usage docs
- Include CLI and API examples
- List which agents use it
- Provide troubleshooting guide

---

## 🔄 Update Process

When adding a NEW hook:
1. Create hook file in `/root/DW-MCP/DW-Hooks/`
2. Add API endpoint to relevant agent servers
3. Add buttons to relevant agent dashboards
4. Update this document
5. Update `/root/DW-MCP/DW-Hooks/README.md`
6. Test from UI and CLI

When updating an EXISTING hook:
1. Ensure backward compatibility
2. Update button labels if functionality changed
3. Update documentation
4. Test all agents that use it

---

## 📚 Related Documentation

- **Hook Files:** `/root/DW-MCP/DW-Hooks/`
- **Hook README:** `/root/DW-MCP/DW-Hooks/README.md`
- **API Hooks Guide:** `/root/DW-MCP/DW-Hooks/API-HOOKS.md`
- **Agent Dashboards:** `/root/DW-Agents/agent-*/`
- **Port Registry:** `/root/DW-Agents/chat-logs/all-services-ports.md`

---

**Remember:** EVERY HOOK = BUTTON + SERVICE!
**No exceptions!**

**Maintained by:** Bubbie AI 💙
**Last Updated:** 2025-11-12