# AGENT-SYSTEM.md — Multi-Agent Architecture

*Master reference for the Rocky & Rivet agent system. Read this if context is lost.*

**Last Updated:** 2026-02-06 18:12 AEST
**Group:** Rocky and Rivet (-1003505625266)

---

## Overview

The system runs multiple AI agents via Telegram topic threads. Each topic is a separate Clawdbot session with a specialized role. Main Rivet (DM) coordinates everything.

---

## Architecture

```
┌─────────────────────────────────────────────────┐
│                 Michael (Human)                  │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│           Main Rivet (DM Session)               │
│   - Full context, coordinator                   │
│   - Spawns sub-agents for work                  │
│   - Updates TOPICS.md                           │
│   - Reads all agent profiles                    │
└─────────────────┬───────────────────────────────┘
                  │
    ┌─────────────┼─────────────┐
    │             │             │
    ▼             ▼             ▼
┌────────┐  ┌────────┐  ┌────────┐  ... (8 topic agents)
│Builder │  │ Sales  │  │Research│
│topic:2 │  │topic:4 │  │topic:5 │
└────────┘  └────────┘  └────────┘
```

---

## Topic → Agent Mapping

| Topic ID | Topic Name | Agent Role | Job |
|----------|------------|------------|-----|
| 1 | General | Bulletin | Announcements only (not interactive) |
| 2 | RateRight | **Builder Agent** | Code, features, deployment |
| 4 | Sales | **Sales Ops Agent** | Pipeline, CRM, leads, SMS |
| 5 | Research | **Researcher Agent** | Market intel, validation, gaps |
| 6 | Construction | **Site Ops Agent** | Timesheets, work logs, site issues |
| 7 | System | **SysOps Agent** | Infra, crons, security, monitoring |
| 8 | Personal | **PA Agent** | Schedule, reminders, calendar |
| 10 | Ideas | **Product Agent** | Backlog, specs, prioritization |
| 11 | Content | **Marketer Agent** | Brand, posts, SEO, content |

---

## Key Files

| File | Purpose |
|------|---------|
| `TOPICS.md` | Agent briefings — each agent reads this to know their role, tools, tasks |
| `AGENT-SYSTEM.md` | This file — system architecture (read if context lost) |
| `memory/agents/*.md` | Deep profiles for each agent (tools, workflows, context) |
| `SOUL.md` | Core personality (all agents share this) |
| `TOOLS.md` | Local tool notes (API keys, phone numbers, etc.) |

---

## Agent Profiles

Each agent has a detailed profile in `memory/agents/`:

| Agent | Profile |
|-------|---------|
| Builder | `memory/agents/builder-profile.md` |
| Sales Ops | `memory/agents/sales-profile.md` |
| Researcher | `memory/agents/researcher-profile.md` |
| Marketer | `memory/agents/marketer-profile.md` |
| SysOps | `memory/agents/sysops-profile.md` |
| Site Ops | `memory/agents/siteops-profile.md` |
| Product | `memory/agents/product-profile.md` |

---

## How Agents Identify Themselves

1. Topic session starts
2. Reads `TOPICS.md` — finds "Who Am I?" section
3. Matches topic ID to agent role
4. Introduces self by role (e.g., "I'm the Builder Agent")

---

## Workflows

### ReviewFlow (Code Quality)
1. **Kimi drafts** — fast, cheap, writes initial code/specs
2. **Claude Code reviews** — catches security issues, bugs
3. Proven: Stripe spec → Kimi wrote → Claude found 22 issues

### Idea Pipeline (Multi-Agent Refinement)
1. Idea starts with Product Agent
2. → Research Agent: market validation
3. → Builder Agent: technical feasibility
4. → Sales Agent: customer fit
5. → Vetted idea to backlog

### Delegation (Main → Topic Agent)
- Main Rivet spawns sub-agent with topic's context
- Sub-agent does work, saves to files
- Main updates TOPICS.md with results

---

## Heartbeat Tasks (HEARTBEAT.md)

1. Health check (every heartbeat)
2. Task executor (spawn agent for TODO items)
3. **Topic sync** (every 2nd heartbeat) — read topic histories, update TOPICS.md
4. Notion ideas check
5. Research & improve
6. Memory maintenance

---

## Telegram Group Details

- **Group ID:** -1003505625266
- **Group Name:** Rocky and Rivet
- **Topic Links:** `t.me/c/3505625266/{topic_id}`
- **Bot Name:** Rivet (displays as "Rivet" in all topics)

---

## Recovery Checklist

If context is lost or system needs rebuilding:

1. Read this file (`AGENT-SYSTEM.md`)
2. Read `TOPICS.md` for current agent states
3. Read `memory/agents/*.md` for detailed profiles
4. Check `HEARTBEAT.md` for autonomous tasks
5. Check active sessions with `sessions_list`
6. Resume from last known state

---

## Rules

1. **Main Rivet coordinates** — don't let topic agents go rogue
2. **Agents stay in their lane** — focus on their job
3. **Update TOPICS.md** — when tasks complete or state changes
4. **Save work to files** — agents write to memory/plans/, memory/agents/, etc.
5. **ReviewFlow for code** — Kimi drafts, Claude reviews

---

## ⚠️ Execution Model (NON-NEGOTIABLE)

**Topic agents are brains, not hands.**

Topic agents run on Opus ($25/M output tokens). They MUST delegate execution to sub-agents:

| Topic Agent (Opus) | Sub-agents (Kimi/DeepSeek) | Claude Code |
|--------------------|---------------------------|-------------|
| Think, plan, decide | Research, drafting, processing | Actual coding |
| Approve/reject | First drafts, grunt work | Build features |
| Coordinate | Parallel tasks | Code review |

**Spawn sub-agents for work:**
```
sessions_spawn(
  task="Research X and save to memory/plans/x.md",
  model="kimi"  # ALWAYS use kimi or deepseek for execution
)
```

**Claude Code:** Reserved for actual code changes. Not research, not docs, not planning.

**Cost:** Opus = $25/M tokens. Kimi = ~$2/M tokens. 10x difference.

This is non-negotiable. Michael's budget depends on it.

---

## Changelog

- **2026-02-06 17:52** — Initial agent system created (8 topics)
- **2026-02-06 18:09** — Identity updates sent to all topics
- **2026-02-06 18:10** — Agent profiles spawned (7 agents researching)
- **2026-02-06 18:12** — This file created (master reference)