1# PRD: X-to-Book Multi-Agent System
2 
3## Overview
4 
5A multi-agent system that monitors target X (Twitter) accounts daily, synthesizes their content, and generates structured books from accumulated insights. The system uses context engineering principles to handle high-volume social data while maintaining coherent long-form output.
6 
7## Problem Statement
8 
9Manual curation of insights from X accounts is time-consuming and inconsistent. Existing tools dump raw data without synthesis. We need a system that:
10- Continuously monitors specified X accounts
11- Extracts meaningful patterns and insights across time
12- Produces structured, coherent daily book outputs
13- Maintains temporal awareness of how narratives evolve
14 
15## Architecture
16 
17### Multi-Agent Pattern Selection: Supervisor/Orchestrator
18 
19Based on the context engineering patterns, we use a **supervisor architecture** because:
201. Book production has clear sequential phases (scrape, analyze, synthesize, write, edit)
212. Quality gates require central coordination
223. Human oversight points are well-defined
234. Context isolation per phase prevents attention saturation
24 
25```
26User Config -> Orchestrator -> [Scraper, Analyzer, Synthesizer, Writer, Editor] -> Daily Book
27```
28 
29### Agent Definitions
30 
31#### 1. Orchestrator Agent
32**Purpose**: Central coordinator that manages workflow, maintains state, routes to specialists.
33 
34**Context Budget**: Reserved for task decomposition, quality gates, and synthesis coordination. Does not carry raw tweet data.
35 
36**Responsibilities**:
37- Decompose daily book task into subtasks
38- Route to appropriate specialist agents
39- Implement checkpoint/resume for long-running operations
40- Aggregate results without paraphrasing (avoid telephone game problem)
41 
42```python
43class OrchestratorState(TypedDict):
44    target_accounts: List[str]
45    current_phase: str
46    phase_outputs: Dict[str, Any]
47    quality_scores: Dict[str, float]
48    book_outline: str
49    checkpoints: List[Dict]
50```
51 
52#### 2. Scraper Agent
53**Purpose**: Fetch and normalize content from target X accounts.
54 
55**Context Budget**: Minimal. Operates on one account at a time, outputs to file system.
56 
57**Tools**:
58- `fetch_timeline(account_id, since_date, until_date)` - Retrieve tweets in date range
59- `fetch_thread(tweet_id)` - Expand full thread context
60- `fetch_engagement_metrics(tweet_ids)` - Get likes/retweets/replies
61- `write_to_store(account_id, data)` - Persist to file system
62 
63**Output**: Structured JSON per account, written to file system (not passed through context).
64 
65#### 3. Analyzer Agent
66**Purpose**: Extract patterns, themes, and insights from raw content.
67 
68**Context Budget**: Moderate. Processes one account's data at a time via file system reads.
69 
70**Responsibilities**:
71- Topic extraction and clustering
72- Sentiment analysis over time
73- Key insight identification
74- Thread narrative extraction
75- Controversy/debate identification
76 
77**Output**: Structured analysis per account with:
78- Top themes (ranked by frequency and engagement)
79- Notable quotes (with context)
80- Narrative arcs (multi-tweet threads)
81- Temporal patterns (time-of-day, response patterns)
82 
83#### 4. Synthesizer Agent
84**Purpose**: Cross-account pattern recognition and theme consolidation.
85 
86**Context Budget**: High. Receives summaries from all analyzed accounts.
87 
88**Responsibilities**:
89- Identify cross-account themes
90- Detect agreement/disagreement patterns
91- Build narrative connections
92- Generate book outline with chapter structure
93 
94**Output**: Book outline with:
95- Chapter structure
96- Theme assignments per chapter
97- Source attribution map
98- Suggested narrative flow
99 
100#### 5. Writer Agent
101**Purpose**: Generate book content from outline and source material.
102 
103**Context Budget**: Per-chapter allocation. Works on one chapter at a time.
104 
105**Responsibilities**:
106- Draft chapter content following outline
107- Integrate quotes with proper attribution
108- Maintain consistent voice and style
109- Handle transitions between themes
110 
111**Output**: Draft chapters in markdown format.
112 
113#### 6. Editor Agent
114**Purpose**: Quality assurance and refinement.
115 
116**Context Budget**: Per-chapter. Reviews one chapter at a time.
117 
118**Responsibilities**:
119- Fact-check against source material
120- Verify quote accuracy
121- Check narrative coherence
122- Flag potential issues for human review
123 
124**Output**: Edited chapters with revision notes.
125 
126---
127 
128## Memory System Design
129 
130### Architecture: Temporal Knowledge Graph
131 
132Based on the memory-systems skill, we need a **temporal knowledge graph** because:
133- Facts about accounts change over time (opinions shift, topics evolve)
134- We need time-travel queries ("What was @account's position on X in January?")
135- Cross-account relationships require graph traversal
136- Simple vector stores lose relationship structure
137 
138### Entity Types
139 
140```python
141entities = {
142    "Account": {
143        "properties": ["handle", "display_name", "bio", "follower_count", "following_count"]
144    },
145    "Tweet": {
146        "properties": ["content", "timestamp", "engagement_score", "thread_id"]
147    },
148    "Theme": {
149        "properties": ["name", "description", "first_seen", "last_seen"]
150    },
151    "Book": {
152        "properties": ["date", "title", "chapter_count", "word_count"]
153    },
154    "Chapter": {
155        "properties": ["title", "theme", "word_count", "source_accounts"]
156    }
157}
158```
159 
160### Relationship Types
161 
162```python
163relationships = {
164    "POSTED": {
165        "from": "Account",
166        "to": "Tweet",
167        "temporal": True
168    },
169    "DISCUSSES": {
170        "from": "Tweet",
171        "to": "Theme",
172        "temporal": True,
173        "properties": ["sentiment", "stance"]
174    },
175    "RESPONDS_TO": {
176        "from": "Tweet",
177        "to": "Tweet"
178    },
179    "AGREES_WITH": {
180        "from": "Account",
181        "to": "Account",
182        "temporal": True,
183        "properties": ["on_theme"]
184    },
185    "DISAGREES_WITH": {
186        "from": "Account",
187        "to": "Account",
188        "temporal": True,
189        "properties": ["on_theme"]
190    },
191    "CONTAINS": {
192        "from": "Book",
193        "to": "Chapter"
194    },
195    "SOURCES": {
196        "from": "Chapter",
197        "to": "Tweet"
198    }
199}
200```
201 
202### Memory Retrieval Patterns
203 
204```python
205# What has @account said about AI in the last 30 days?
206query_account_theme_temporal(account_id, theme="AI", days=30)
207 
208# Which accounts disagree on crypto?
209query_disagreement_network(theme="crypto")
210 
211# What quotes should be in today's book about regulation?
212query_quotable_content(theme="regulation", min_engagement=100)
213```
214 
215---
216 
217## Context Optimization Strategy
218 
219### Challenge
220 
221X data is high-volume. A target account with 20 tweets/day across 10 accounts = 200 tweets/day. Each tweet with thread context averages 500 tokens. Daily raw context = 100k tokens before analysis.
222 
223### Optimization Techniques
224 
225#### 1. Observation Masking
226Raw tweet data is processed by Scraper, written to file system, and never passed through Orchestrator context.
227 
228```python
229# Instead of passing raw tweets through context
230# Scraper writes to file system
231scraper.write_to_store(account_id, raw_tweets)
232 
233# Analyzer reads from file system
234raw_data = analyzer.read_from_store(account_id)
235```
236 
237#### 2. Compaction Triggers
238 
239```python
240COMPACTION_THRESHOLD = 0.7  # 70% context utilization
241 
242if context_utilization > COMPACTION_THRESHOLD:
243    # Summarize older phase outputs
244    phase_outputs = compact_phase_outputs(phase_outputs)
245```
246 
247#### 3. Progressive Disclosure
248 
249Book outline loads first (lightweight). Full chapter content loads only when Writer is working on that chapter.
250 
251```python
252# Level 1: Outline only
253book_outline = {
254    "chapters": [
255        {"title": "Chapter 1", "themes": ["AI", "Regulation"], "word_count_target": 2000}
256    ]
257}
258 
259# Level 2: Full chapter context (only when writing)
260chapter_context = load_chapter_context(chapter_id)
261```
262 
263#### 4. KV-Cache Optimization
264 
265System prompt and tool definitions are stable across runs. Structure context for cache hits:
266 
267```python
268context_order = [
269    system_prompt,       # Stable, cacheable
270    tool_definitions,    # Stable, cacheable
271    account_config,      # Semi-stable
272    daily_outline,       # Changes daily
273    current_task         # Changes per call
274]
275```
276 
277---
278 
279## Tool Design
280 
281### Consolidation Principle Applied
282 
283Instead of multiple narrow tools, we implement comprehensive tools per domain:
284 
285#### X Data Tool (Consolidated)
286 
287```python
288def x_data_tool(
289    action: Literal["fetch_timeline", "fetch_thread", "fetch_engagement", "search"],
290    account_id: Optional[str] = None,
291    tweet_id: Optional[str] = None,
292    query: Optional[str] = None,
293    since_date: Optional[str] = None,
294    until_date: Optional[str] = None,
295    format: Literal["concise", "detailed"] = "concise"
296) -> Dict:
297    """
298    Unified X data retrieval tool.
299    
300    Use when:
301    - Fetching timeline for target account monitoring
302    - Expanding thread context for full conversation
303    - Getting engagement metrics for content prioritization
304    - Searching for specific topics across accounts
305    
306    Actions:
307    - fetch_timeline: Get tweets from account in date range
308    - fetch_thread: Expand full thread from single tweet
309    - fetch_engagement: Get likes/retweets/replies
310    - search: Search across accounts for query
311    
312    Returns:
313    - concise: tweet_id, content_preview, timestamp, engagement_score
314    - detailed: full content, thread context, all engagement metrics, reply preview
315    
316    Errors:
317    - RATE_LIMITED: Wait {retry_after} seconds
318    - ACCOUNT_PRIVATE: Cannot access private account
319    - NOT_FOUND: Tweet/account does not exist
320    """
321```
322 
323#### Memory Tool (Consolidated)
324 
325```python
326def memory_tool(
327    action: Literal["store", "query", "update_validity", "consolidate"],
328    entity_type: Optional[str] = None,
329    entity_id: Optional[str] = None,
330    relationship_type: Optional[str] = None,
331    query_params: Optional[Dict] = None,
332    as_of_date: Optional[str] = None
333) -> Dict:
334    """
335    Unified memory system tool.
336    
337    Use when:
338    - Storing new facts discovered from X data
339    - Querying historical information about accounts/themes
340    - Updating validity periods when facts change
341    - Running consolidation to merge duplicate facts
342    
343    Actions:
344    - store: Add new entity or relationship
345    - query: Retrieve entities/relationships matching params
346    - update_validity: Mark fact as expired with valid_until
347    - consolidate: Merge duplicates and cleanup
348    
349    Returns entity/relationship data or query results.
350    """
351```
352 
353#### Writing Tool (Consolidated)
354 
355```python
356def writing_tool(
357    action: Literal["draft", "edit", "format", "export"],
358    content: Optional[str] = None,
359    chapter_id: Optional[str] = None,
360    style_guide: Optional[str] = None,
361    output_format: Literal["markdown", "html", "pdf"] = "markdown"
362) -> Dict:
363    """
364    Unified book writing tool.
365    
366    Use when:
367    - Drafting new chapter content
368    - Editing existing content for quality
369    - Formatting content for output
370    - Exporting final book
371    
372    Actions:
373    - draft: Create initial chapter draft
374    - edit: Apply revisions to existing content
375    - format: Apply styling and formatting
376    - export: Generate final output file
377    """
378```
379 
380---
381 
382## Evaluation Framework
383 
384### Multi-Dimensional Rubric
385 
386Based on the evaluation skill, we define quality dimensions:
387 
388| Dimension | Weight | Excellent | Acceptable | Failed |
389|-----------|--------|-----------|------------|--------|
390| Source Accuracy | 30% | All quotes verified, proper attribution | Minor attribution errors | Fabricated quotes |
391| Thematic Coherence | 25% | Clear narrative thread, logical flow | Some disconnected sections | No coherent narrative |
392| Completeness | 20% | Covers all major themes from sources | Misses some themes | Major gaps |
393| Insight Quality | 15% | Novel synthesis across sources | Restates obvious points | No synthesis |
394| Readability | 10% | Engaging, well-structured prose | Adequate but dry | Unreadable |
395 
396### Automated Evaluation Pipeline
397 
398```python
399def evaluate_daily_book(book: Book, source_data: Dict) -> EvaluationResult:
400    scores = {}
401    
402    # Source accuracy: verify quotes against original tweets
403    scores["source_accuracy"] = verify_quotes(book.chapters, source_data)
404    
405    # Thematic coherence: LLM-as-judge for narrative flow
406    scores["thematic_coherence"] = judge_coherence(book)
407    
408    # Completeness: check theme coverage
409    scores["completeness"] = calculate_theme_coverage(book, source_data)
410    
411    # Insight quality: LLM-as-judge for synthesis
412    scores["insight_quality"] = judge_insights(book, source_data)
413    
414    # Readability: automated metrics + LLM judge
415    scores["readability"] = assess_readability(book)
416    
417    overall = weighted_average(scores, DIMENSION_WEIGHTS)
418    
419    return EvaluationResult(
420        passed=overall >= 0.7,
421        scores=scores,
422        overall=overall,
423        flagged_issues=identify_issues(scores)
424    )
425```
426 
427### Human Review Triggers
428 
429- Overall score < 0.7
430- Source accuracy < 0.8
431- Any fabricated quote detected
432- New account added (first book needs review)
433- Controversial topic detected
434 
435---
436 
437## Data Flow
438 
439```
440┌─────────────────────────────────────────────────────────────────────────────┐
441│                              DAILY PIPELINE                                  │
442└─────────────────────────────────────────────────────────────────────────────┘
443                                      │
444                                      ▼
445┌─────────────────────────────────────────────────────────────────────────────┐
446│ 1. SCRAPE PHASE                                                              │
447│    Scraper Agent → X API → File System (raw_data/{account}/{date}.json)     │
448│    Context: Minimal (tool calls only)                                        │
449│    Output: Raw tweet data persisted to file system                           │
450└─────────────────────────────────────────────────────────────────────────────┘
451                                      │
452                                      ▼
453┌─────────────────────────────────────────────────────────────────────────────┐
454│ 2. ANALYZE PHASE                                                             │
455│    Analyzer Agent → File System → Memory Store                               │
456│    Context: One account at a time                                            │
457│    Output: Structured analysis per account + Knowledge Graph updates         │
458└─────────────────────────────────────────────────────────────────────────────┘
459                                      │
460                                      ▼
461┌─────────────────────────────────────────────────────────────────────────────┐
462│ 3. SYNTHESIZE PHASE                                                          │
463│    Synthesizer Agent → Analysis Summaries → Book Outline                     │
464│    Context: Summaries from all accounts (compacted)                          │
465│    Output: Book outline with chapter structure                               │
466└─────────────────────────────────────────────────────────────────────────────┘
467                                      │
468                                      ▼
469┌─────────────────────────────────────────────────────────────────────────────┐
470│ 4. WRITE PHASE                                                               │
471│    Writer Agent → Outline + Relevant Sources → Draft Chapters                │
472│    Context: One chapter at a time (progressive disclosure)                   │
473│    Output: Draft markdown chapters                                           │
474└─────────────────────────────────────────────────────────────────────────────┘
475                                      │
476                                      ▼
477┌─────────────────────────────────────────────────────────────────────────────┐
478│ 5. EDIT PHASE                                                                │
479│    Editor Agent → Draft + Sources → Final Chapters                           │
480│    Context: One chapter at a time                                            │
481│    Output: Edited chapters with revision notes                               │
482└─────────────────────────────────────────────────────────────────────────────┘
483                                      │
484                                      ▼
485┌─────────────────────────────────────────────────────────────────────────────┐
486│ 6. EVALUATE PHASE                                                            │
487│    Evaluation Pipeline → Final Book → Quality Report                         │
488│    Output: Pass/fail with scores, flagged issues                             │
489└─────────────────────────────────────────────────────────────────────────────┘
490                                      │
491                                      ▼
492┌─────────────────────────────────────────────────────────────────────────────┐
493│ 7. PUBLISH (if passed) or HUMAN REVIEW (if flagged)                          │
494└─────────────────────────────────────────────────────────────────────────────┘
495```
496 
497---
498 
499## Failure Modes and Mitigations
500 
501### Failure: Orchestrator Context Saturation
502**Symptom**: Orchestrator accumulates phase outputs, degrading routing decisions.
503**Mitigation**: Phase outputs stored in file system, Orchestrator receives only summaries. Implement checkpointing to persist state.
504 
505### Failure: X API Rate Limiting
506**Symptom**: Scraper hits rate limits, incomplete data.
507**Mitigation**: 
508- Implement circuit breaker with exponential backoff
509- Checkpoint partial scrapes for resume
510- Schedule scraping across time windows
511 
512### Failure: Quote Hallucination
513**Symptom**: Writer generates quotes not in source material.
514**Mitigation**:
515- Strict source attribution in writing prompt
516- Editor agent verifies all quotes against source
517- Automated quote verification in evaluation
518 
519### Failure: Theme Drift
520**Symptom**: Book themes diverge from actual source content.
521**Mitigation**:
522- Synthesizer receives grounded summaries only
523- Writer tool includes source verification step
524- Evaluation checks theme-source alignment
525 
526### Failure: Coordination Overhead
527**Symptom**: Agent communication latency exceeds content value.
528**Mitigation**:
529- Batch phase outputs
530- Use file system for inter-agent data (no context passing for large payloads)
531- Parallelize where possible (Scraper can run per-account in parallel)
532 
533---
534 
535## Configuration
536 
537```yaml
538# config.yaml
539target_accounts:
540  - handle: "@account1"
541    priority: high
542    themes_of_interest: ["AI", "startups"]
543  - handle: "@account2"
544    priority: medium
545    themes_of_interest: ["regulation", "policy"]
546 
547schedule:
548  scrape_time: "06:00"  # UTC
549  publish_time: "08:00"
550  timezone: "UTC"
551 
552book_settings:
553  target_word_count: 5000
554  min_chapters: 3
555  max_chapters: 7
556  style: "analytical"  # analytical | narrative | summary
557 
558quality_thresholds:
559  min_overall_score: 0.7
560  min_source_accuracy: 0.8
561  require_human_review_below: 0.75
562 
563memory:
564  retention_days: 90
565  consolidation_frequency: "weekly"
566  
567context_limits:
568  orchestrator: 50000
569  scraper: 20000
570  analyzer: 80000
571  synthesizer: 100000
572  writer: 80000
573  editor: 60000
574```
575 
576---
577 
578## Implementation Phases
579 
580### Phase 1: Core Pipeline (Week 1-2)
581- Orchestrator with basic routing
582- Scraper with X API integration
583- File system storage
584- Basic Writer producing markdown output
585 
586### Phase 2: Analysis Layer (Week 3-4)
587- Analyzer agent with theme extraction
588- Synthesizer with cross-account patterns
589- Book outline generation
590 
591### Phase 3: Memory System (Week 5-6)
592- Temporal knowledge graph implementation
593- Entity and relationship storage
594- Temporal queries for historical context
595 
596### Phase 4: Quality Layer (Week 7-8)
597- Editor agent
598- Evaluation pipeline
599- Human review interface
600 
601### Phase 5: Production Hardening (Week 9-10)
602- Checkpoint/resume
603- Circuit breakers
604- Monitoring and alerting
605- Consolidation jobs
606 
607---
608 
609## Technical Stack (Recommended)
610 
611| Component | Technology | Rationale |
612|-----------|------------|-----------|
613| Agent Framework | LangGraph | Graph-based state machines with explicit nodes/edges |
614| Knowledge Graph | Neo4j or Memgraph | Native temporal queries, relationship traversal |
615| Vector Store | Weaviate or Pinecone | Hybrid search (semantic + metadata filtering) |
616| X API | Official API or Scraping fallback | Rate limits require careful management |
617| Storage | PostgreSQL + S3 | Structured data + blob storage for content |
618| Orchestration | Temporal.io | Durable workflows with checkpoint/resume |
619 
620---
621 
622## Open Questions
623 
6241. **X API Access**: Official API vs scraping? Rate limits on official API are restrictive. Scraping has legal/TOS considerations.
625 
6262. **Book Format**: Pure prose vs mixed media (including original tweet embeds)?
627 
6283. **Attribution Model**: How prominent should account attribution be? Full quotes with handles vs paraphrased insights?
629 
6304. **Monetization**: If books are sold, what are the IP implications of synthesizing public tweets?
631 
6325. **Human-in-the-Loop**: How much editorial control? Full review of every book vs exception-based review?
633 
634---
635 
636## References
637 
638- [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) - Context engineering patterns
639- Multi-agent patterns skill - Supervisor architecture selection
640- Memory systems skill - Temporal knowledge graph design
641- Context optimization skill - Observation masking and compaction strategies
642- Tool design skill - Consolidation principle for tools
643- Evaluation skill - Multi-dimensional rubrics
644 
645