microdao-daarion/READY_TO_BUILD.md

# 🎉 READY TO BUILD — Phase 2 Agent Integration

**All specifications complete. Copy-paste ready for Cursor AI.**

---

## 🚀 ONE-COMMAND START

```bash
# Copy Phase 2 Master Task to clipboard
cat docs/tasks/PHASE2_MASTER_TASK.md | pbcopy

# Then paste into Cursor AI
# Cursor will implement all 3 services + integration
```

---

## 📦 What You Get

### ✅ Complete Implementation Files

**9 NEW FILES created for you in PHASE2_MASTER_TASK.md:**

#### agent-filter (7 files)
- `services/agent-filter/main.py` ✅ Complete code
- `services/agent-filter/models.py` ✅ Complete code
- `services/agent-filter/rules.py` ✅ Complete code
- `services/agent-filter/config.yaml` ✅ Complete config
- `services/agent-filter/Dockerfile` ✅ Ready to build
- `services/agent-filter/requirements.txt` ✅ All deps
- `services/agent-filter/README.md` ✅ Documentation

#### agent-runtime (9 files)
- `services/agent-runtime/main.py` ✅ Complete code
- `services/agent-runtime/models.py` ✅ Complete code
- `services/agent-runtime/llm_client.py` ✅ Complete code
- `services/agent-runtime/messaging_client.py` ✅ Complete code
- `services/agent-runtime/memory_client.py` ✅ Complete code
- `services/agent-runtime/config.yaml` ✅ Complete config
- `services/agent-runtime/Dockerfile` ✅ Ready to build
- `services/agent-runtime/requirements.txt` ✅ All deps
- `services/agent-runtime/README.md` ✅ Documentation

#### Router Extension
- Router subscription code ✅ Complete
- AgentInvocation creation ✅ Complete
- Test endpoint ✅ Complete

#### Docker Integration
- `docker-compose.agents.yml` ✅ Complete

---

## 📋 Files Created Today

**Total: 9 files, ~50 KB of documentation**

1. ✅ `docs/tasks/PHASE2_MASTER_TASK.md` (18 KB)
   - **THE MAIN FILE** — Copy this to Cursor
   - Complete Python code for all services
   - Docker configs
   - Testing instructions

2. ✅ `docs/tasks/TASK_PHASE2_AGENT_INTEGRATION.md` (15 KB)
   - Detailed specification format
   - Step-by-step breakdown

3. ✅ `docs/tasks/TASK_AGENT_HUB_MVP.md` (10 KB)
   - Agent Hub UI task (parallel track)

4. ✅ `docs/tasks/README.md` (7 KB)
   - Tasks navigation

5. ✅ `docs/INDEX.md` (10 KB)
   - Master documentation index

6. ✅ `PHASE2_READY.md` (12 KB)
   - Phase 2 summary

7. ✅ `START_PHASE2.md` (10 KB)
   - Quick start guide

8. ✅ `docs/tasks/PHASE3_ROADMAP.md` (12 KB)
   - Phase 3 planning

9. ✅ `READY_TO_BUILD.md` (this file)
   - Final checklist

---

## 🎯 What Phase 2 Does

### Before (Phase 1):
```
User types in Messenger → Message appears (static)
```

### After (Phase 2):
```
User types "Hello!" in Messenger
    ↓
messaging-service → NATS: messaging.message.created
    ↓
agent_filter: "Allow agent:sofia to reply"
    ↓
NATS: agent.filter.decision
    ↓
DAGI Router: "Route to agent-runtime"
    ↓
NATS: router.invoke.agent
    ↓
agent-runtime:
  1. Reads last 50 messages
  2. Queries agent memory
  3. Calls LLM
  4. Posts reply
    ↓
Agent replies "Hi! How can I help?" in 3 seconds
```

---

## ✅ Pre-flight Checklist

### Phase 1 Status:
- ✅ Messenger Module (23 files)
- ✅ messaging-service running
- ✅ matrix-gateway spec ready
- ✅ Database schema created
- ✅ Frontend /messenger working
- ✅ WebSocket real-time updates
- ✅ Testing guide (13 scenarios)

### Phase 2 Ready:
- ✅ PHASE2_MASTER_TASK.md (complete code)
- ✅ All specs documented
- ✅ Acceptance criteria defined
- ✅ Testing strategy ready
- ✅ Docker configs ready

---

## 🚀 How to Start

### Option A: Cursor AI (5 minutes setup)

```bash
# Step 1: Copy task
cat docs/tasks/PHASE2_MASTER_TASK.md | pbcopy

# Step 2: Open Cursor
code .

# Step 3: Paste into Cursor AI chat

# Step 4: Press Enter

# Cursor will:
# - Create all 3 services
# - Write all code
# - Create Docker configs
# - Update documentation
```

### Option B: Manual (1 week work)

```bash
# Step 1: Create agent-filter
mkdir -p services/agent-filter
cd services/agent-filter
# Copy code from PHASE2_MASTER_TASK.md

# Step 2: Extend router
cd services/router
# Add code from PHASE2_MASTER_TASK.md

# Step 3: Create agent-runtime
mkdir -p services/agent-runtime
cd services/agent-runtime
# Copy code from PHASE2_MASTER_TASK.md

# Step 4: Docker
# Copy docker-compose.agents.yml from PHASE2_MASTER_TASK.md
```

---

## 🧪 Testing

### After Cursor completes:

```bash
# Start services
docker-compose -f docker-compose.agents.yml up -d

# Check health
curl http://localhost:7005/health  # agent-filter
curl http://localhost:7006/health  # agent-runtime

# Test agent-filter
curl -X POST http://localhost:7005/internal/agent-filter/test \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "test",
    "matrix_event_id": "$event123",
    "sender_id": "user:1",
    "sender_type": "human",
    "microdao_id": "microdao:daarion",
    "created_at": "2025-11-24T10:00:00Z"
  }'

# Expected: {"decision": "allow", "target_agent_id": "agent:sofia"}
```

### E2E Test:

```bash
# 1. Open Messenger
open http://localhost:8899/messenger

# 2. Type "Hello Sofia!"

# 3. Wait 3-5 seconds

# 4. See agent reply: "Привіт! Як можу допомогти?"

# ✅ Phase 2 working!
```

---

## 📊 Architecture

### Services:
- ✅ messaging-service (7004)
- 🔜 agent-filter (7005) — NEW
- 🔜 agent-runtime (7006) — NEW
- 🔜 router (8000 or TBD) — EXTENDED

### NATS Subjects:
- `messaging.message.created` — messaging-service publishes
- `agent.filter.decision` — agent-filter publishes
- `router.invoke.agent` — router publishes

### Flow:
```
messaging-service → NATS
    ↓
agent-filter → NATS
    ↓
router → NATS
    ↓
agent-runtime → messaging-service → Matrix → Frontend
```

---

## 📅 Timeline

| Week | Focus | Deliverables |
|------|-------|--------------|
| 1 | agent-filter | Service running, rules working |
| 2 | Router | Extension complete, routing works |
| 3-4 | agent-runtime | LLM integration, posting works |
| 5 | Testing | E2E flow, optimization |

**Total:** 4-5 weeks

---

## 🎓 Key Concepts

### agent-filter:
- Subscribes to `messaging.message.created`
- Applies rules (no agent loops, quiet hours, permissions)
- Decides which agent responds
- Publishes `agent.filter.decision`

### Router:
- Subscribes to `agent.filter.decision`
- Creates `AgentInvocation`
- Routes to agent-runtime via `router.invoke.agent`

### agent-runtime:
- Subscribes to `router.invoke.agent`
- Loads agent blueprint
- Reads channel history (last 50 messages)
- Queries agent memory (RAG)
- Calls LLM Proxy
- Posts reply to channel

---

## 🆘 Troubleshooting

### Cursor not implementing?
```bash
# Make sure you copied PHASE2_MASTER_TASK.md
# It has complete code, not just specs
cat docs/tasks/PHASE2_MASTER_TASK.md | grep "def decide"
# Should show Python code
```

### Services not starting?
```bash
# Check Docker
docker ps

# Check logs
docker logs agent-filter
docker logs agent-runtime

# Check NATS
docker logs nats
```

### Agent not replying?
```bash
# Check filter decision
docker logs agent-filter | grep decision

# Check routing
docker logs router | grep invoke

# Check runtime
docker logs agent-runtime | grep LLM
```

---

## 🔗 Key Links

### Main Files:
- [PHASE2_MASTER_TASK.md](docs/tasks/PHASE2_MASTER_TASK.md) ⭐ **COPY THIS**
- [START_PHASE2.md](START_PHASE2.md) — Quick guide
- [PHASE2_READY.md](PHASE2_READY.md) — Full summary

### Documentation:
- [MESSAGING_ARCHITECTURE.md](docs/MESSAGING_ARCHITECTURE.md) — Technical spec
- [INDEX.md](docs/INDEX.md) — Master index
- [tasks/README.md](docs/tasks/README.md) — Tasks overview

### Phase 1 (Complete):
- [MESSENGER_MODULE_COMPLETE.md](docs/MESSENGER_MODULE_COMPLETE.md)
- [MESSENGER_TESTING_GUIDE.md](docs/MESSENGER_TESTING_GUIDE.md)

### Next Steps:
- [TASK_AGENT_HUB_MVP.md](docs/tasks/TASK_AGENT_HUB_MVP.md) — Agent Hub UI
- [PHASE3_ROADMAP.md](docs/tasks/PHASE3_ROADMAP.md) — Core services

---

## ✅ Final Checklist

Before starting Phase 2:
- ✅ Phase 1 complete (Messenger working)
- ✅ PHASE2_MASTER_TASK.md reviewed
- ✅ Cursor AI ready OR manual implementation plan
- ✅ Docker running
- ✅ NATS running
- ✅ PostgreSQL running

After Phase 2 complete:
- [ ] agent-filter running
- [ ] Router extended
- [ ] agent-runtime running
- [ ] E2E test passing
- [ ] Agent replies in < 5s
- [ ] Visible in Messenger UI
- [ ] Visible in Element
- [ ] Documentation updated

---

## 🎉 You're Ready!

**Everything is prepared:**
- ✅ Complete code in PHASE2_MASTER_TASK.md
- ✅ Step-by-step instructions
- ✅ Testing guide
- ✅ Troubleshooting help
- ✅ Phase 3 roadmap

**Choose your path:**

**A) Cursor AI:** Copy PHASE2_MASTER_TASK.md → Paste → Done in 1 hour  
**B) Manual:** Follow START_PHASE2.md → Build in 4 weeks  
**C) Review:** Read MESSAGING_ARCHITECTURE.md → Understand system

---

**Ready to make agents live?**

```bash
# COPY THIS FILE TO CURSOR:
cat docs/tasks/PHASE2_MASTER_TASK.md | pbcopy

# Then paste into Cursor AI and watch the magic! ✨
```

---

**Status:** 🚀 READY TO BUILD  
**Version:** 1.0.0  
**Date:** 2025-11-24  

**LET'S BUILD AGENTS!** 🤖🚀