# Agent Communication Feeds Technical Specification

## Problem Statement

The topic agents (Research, Sales, Builder, etc.) have broken communication feeds:
- **Research→Sales**: Research produces competitor data that Sales needs for objection handling, but there's no automated delivery mechanism
- **Sales→Builder**: Sales collects feature requests from leads, but these don't systematically reach Builder for product roadmap consideration

## Current State Analysis

### Existing Infrastructure
- Telegram topics exist for each agent (Research=5, Sales=4, Builder=6)
- Shared memory system at `/home/ccuser/rateright-growth/rivet/memory/`
- Agent spawn tracker at `/home/ccuser/rateright-growth/rivet/memory/spawn-tracker.json`
- Clawdbot message tool can send to specific Telegram topics
- Each agent has defined outputs in their profiles

### Broken Flows Identified
1. Research→Sales: Competitor analysis reports sit in `memory/plans/research/` without automatic notification to Sales
2. Sales→Builder: Feature requests from leads are logged in Growth Engine but not extracted for Builder
3. Missing handoff protocols: No standardized format for agent-to-agent communication

## Proposed Solution

### 1. Agent Feed API
Create a lightweight API system for agent communication:

```
/home/ccuser/rateright-growth/rivet/agent-feeds/
├── README.md                 # Usage instructions
├── config.json              # Feed configurations
├── feeds/                   # Feed data storage
│   ├── research-to-sales/   # Research outputs for Sales
│   ├── sales-to-builder/    # Sales feedback for Builder
│   └── status-updates/      # General status broadcasts
├── scripts/
│   ├── deliver-feeds.js     # Main delivery script
│   ├── create-feed.js       # Create new feed entry
│   └── notify-agent.js      # Send Telegram notifications
└── logs/                    # Delivery logs
```

### 2. Feed Configuration

Each feed will have:
- Source agent
- Target agent(s)
- Delivery method (immediate/batched)
- Format specification
- Retention policy

Example config:
```json
{
  "research-to-sales": {
    "source": "Research",
    "targets": ["Sales"],
    "delivery": "batched",
    "schedule": "daily 08:00",
    "format": "markdown",
    "retention_days": 30
  },
  "sales-to-builder": {
    "source": "Sales",
    "targets": ["Builder"],
    "delivery": "immediate",
    "format": "json",
    "retention_days": 90
  }
}
```

### 3. Implementation Details

#### Research→Sales Feed
**Trigger**: When Research completes a competitor analysis
**Action**: 
1. Save report summary to feed
2. Extract key pricing/objection data
3. Notify Sales agent via Telegram topic 4
4. Update Sales intel briefs in Growth Engine

#### Sales→Builder Feed
**Trigger**: When Sales logs feature requests or objections
**Action**:
1. Parse call notes for feature requests
2. Categorize by frequency and importance
3. Create structured feedback entry
4. Notify Builder via Telegram topic 6
5. Weekly summary to product roadmap

### 4. Message Format Standards

#### Research→Sales Message
```json
{
  "type": "competitor_update",
  "timestamp": "2026-02-09T10:30:00Z",
  "source": "Research",
  "competitor": "Sidekicker",
  "key_findings": [
    "Pricing increased to 35% markup",
    "New verification requirement: White Card"
  ],
  "objection_handles": [
    "We're 30% cheaper than Sidekicker",
    "No verification fees unlike competitors"
  ],
  "priority": "high",
  "full_report": "/memory/plans/research/sidekicker-update-2026-02-09.md"
}
```

#### Sales→Builder Message
```json
{
  "type": "feature_request",
  "timestamp": "2026-02-09T14:20:00Z",
  "source": "Sales",
  "request": "Crew scheduling calendar",
  "frequency": 5,
  "priority_lead": true,
  "lead_context": "Large contractor needs to manage 20+ workers",
  "objection": "Can't switch without crew management",
  "workaround": "Using spreadsheets currently"
}
```

### 5. Delivery Mechanisms

#### Immediate Delivery
- High priority items
- Time-sensitive information
- Critical bug reports

#### Batched Delivery
- Daily digest at 08:00 AEST
- Weekly summaries on Mondays
- Non-urgent updates

#### Telegram Integration
Use existing message tool with specific topic IDs:
- Research (topic 5) → Sales (topic 4)
- Sales (topic 4) → Builder (topic 6)

### 6. Error Handling

- Failed deliveries retry 3 times
- Dead letter queue for permanent failures
- Alerts to System topic (7) for critical issues
- Weekly delivery report to all agents

### 7. Security Considerations

- Feed data encrypted at rest
- API keys stored in `/root/.clawdbot/secrets.json`
- Rate limiting on feed creation
- Audit log of all inter-agent communications

## Implementation Plan

### Phase 1: Core Infrastructure (Week 1)
1. Create feed directory structure
2. Implement feed creation API
3. Set up Telegram notification system
4. Create delivery scheduler

### Phase 2: Research→Sales Feed (Week 2)
1. Integrate with Research agent profile
2. Create competitor data extraction
3. Implement Sales notification system
4. Test with recent research outputs

### Phase 3: Sales→Builder Feed (Week 3)
1. Parse Growth Engine call logs
2. Create feature request categorization
3. Implement Builder notifications
4. Set up weekly summary generation

### Phase 4: Monitoring & Optimization (Week 4)
1. Add delivery metrics
2. Create feed health dashboard
3. Implement retry mechanisms
4. Document usage patterns

## Success Metrics

- **Delivery Rate**: >95% of feeds delivered successfully
- **Response Time**: <5 minutes for immediate feeds
- **Agent Adoption**: All agents using feeds within 2 weeks
- **Error Rate**: <1% failed deliveries after retries

## Maintenance

- Weekly review of undelivered feeds
- Monthly optimization of delivery schedules
- Quarterly review of feed configurations
- Annual audit of inter-agent communication patterns

## Future Enhancements

- Real-time feed dashboard
- Machine learning for feed prioritization
- Cross-feed correlation analysis
- Integration with external APIs
- Voice-based feed updates

---

*This specification provides a practical, implementable solution for fixing the broken agent communication feeds using existing Clawdbot infrastructure.*