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

# 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)

# 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)

# 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:

# 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:

# 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?

# 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?

# Check Docker
docker ps

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

# Check NATS
docker logs nats

Agent not replying?

# 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 ⭐ COPY THIS
• START_PHASE2.md — Quick guide
• PHASE2_READY.md — Full summary

Documentation:

• MESSAGING_ARCHITECTURE.md — Technical spec
• INDEX.md — Master index
• tasks/README.md — Tasks overview

Phase 1 (Complete):

• MESSENGER_MODULE_COMPLETE.md
• MESSENGER_TESTING_GUIDE.md

Next Steps:

• TASK_AGENT_HUB_MVP.md — Agent Hub UI
• 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?

# 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! 🤖🚀