File size: 25,670 Bytes
891fe52
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
# Polyhedra PRD v3.0
## Collaborative Multi-Agent Research Team

```yaml
project_name: Polyhedra
version: 3.0.0
type: Multi-Agent System + Messaging Integration
status: Draft
created: 2026-03-12
updated: 2026-03-12

changelog:
  v3.0.0:
    - New paradigm: single-agent CLI β†’ collaborative multi-agent research team
    - New interface: Slack / Teams / Spark thread as primary collaboration surface
    - New model: agents post as users, @mention each other natively
    - New feature: fluid human role-switching (observer β†’ participant β†’ role owner)
    - New layer: shared research state + thread history as persistent context
    - Retained: CLI (poly commands), MCP server (IDE integrations), human-in-the-loop checkpoints, artifact-first outputs
    - Clarified: CLI, MCP, and messaging thread are three entry points into the same agent system
  v2.x:
    - See legacy PRD for v1.0–v1.2 history (CLI, MCP server, IDE integrations)
```

---

## 1. Product Vision

Polyhedra v3.0 transforms the research assistant from a single tool into a **collaborative research team that lives inside your existing messaging workspace**.

Each agent joins a thread as a named participant. They @mention each other like human teammates. The user picks which roles to include, can step into any role themselves at any time, and can hand that role back. The thread history is the research record.

**Design philosophy (unchanged from v2.x):**
The goal is not to automate research β€” it is to handle the tedious so humans retain creative ownership. Agents do the searching, synthesising, challenging, and drafting. Humans decide the direction, approve the pivots, and own the ideas.

**What changes in v3.0:**
The collaboration medium is no longer a CLI or a chat window. It is a Slack/Teams/Spark channel β€” a space researchers already use daily. This eliminates the tool-switching cost and makes the research process naturally auditable and shareable.

---

## 2. Target Users

The primary user is a **solo researcher** who wants an AI research team they can direct, observe, and participate in at will. This maps to the largest unserved segment in the current market: individual academics, PhD students, and independent researchers who need the leverage of a team but don't have one.

Secondary users include small research groups where human members and AI agents coexist in the same thread.

**User needs (ranked by market demand):**
1. Literature discovery and synthesis β€” the most time-consuming step, most requested capability
2. Research gap identification β€” knowing where to contribute
3. Hypothesis and methodology design β€” moving from field knowledge to a research plan
4. Critical review β€” catching weak arguments before submission
5. Academic writing and citation management β€” drafting and polishing

---

## 3. Core Concepts

### 3.1 The Thread Model

A Polyhedra session is a messaging thread. Agents are workspace members. The user creates a thread, selects which agent roles to activate, and the team assembles.

Every agent has a workspace identity: a name, a role title, and a profile that describes their responsibilities. When @mentioned, they respond in the thread. When they need another agent's input, they @mention them. The thread becomes a readable log of the research process.

### 3.2 Agent Roles

**Core agents** (available at session init, user selects which to include):

| Agent | Role | Responsibilities |
|-------|------|-----------------|
| Scout | Literature Researcher | Searches Semantic Scholar / ArXiv, screens papers, produces structured literature summaries |
| Strategist | Research Designer | Identifies gaps in the literature, frames hypotheses, proposes methodology |
| Critic | Devil's Advocate | Challenges claims made by other agents, flags weak baselines, stress-tests arguments |
| Scribe | Writer / Editor | Drafts paper sections, maintains narrative coherence, manages BibTeX citations |
| Coordinator | Project Manager | Orchestrates the team, routes tasks from @mentions, manages checkpoints, tracks research state |

**Specialist agents** (on-demand, added mid-session if needed):

| Agent | Role | Responsibilities |
|-------|------|-----------------|
| Analyst | Data Interpreter | Interprets experiment results, runs statistical checks, generates charts |
| Reviewer | Submission Preparer | Final review pass for venue-specific requirements, formatting, and completeness |

### 3.3 Human Role Fluidity

The user is not a passive observer. At any moment they can:

- **Observe** β€” read the thread without posting
- **Participate** β€” @mention agents, ask questions, redirect the work
- **Replace a role** β€” declare themselves the Critic for a section, write their own critique, then hand the role back. The agent resumes from where the human left off, reading the thread to catch up.
- **Build the team** β€” at init, choose which roles to include and whether any are human-held from the start

Role switches are explicit, declared in the thread: `I'm taking over as Critic for this section.` or `/poly role critic human`. Agents monitor the thread for these signals.

### 3.4 Shared Research State

Every agent reads from and writes to a structured document called the **Research State**. This is a compressed, always-current summary of:

- The research goal and current framing
- Key papers and their relevance
- Identified gaps and active hypotheses
- Decisions made and their rationale
- Outstanding questions

This solves the context window problem: agents read the Research State (compact) rather than the full thread (unbounded). The Coordinator is responsible for keeping it updated after each significant thread event.

### 3.5 Human Checkpoints

At defined moments, the Coordinator pauses autonomous agent activity and posts a checkpoint summary to the thread. The user must respond before agents continue.

Default checkpoint triggers:
- After Scout completes a literature search (before Strategist proceeds)
- After Strategist proposes research directions (before any drafting begins)
- Before Scribe starts writing a new paper section
- When any agent flags a low-confidence output
- When estimated LLM cost for the next operation exceeds a configurable threshold

Checkpoint format (posted by Coordinator):
```
⏸ Checkpoint: Literature Review Complete

Scout found 34 papers. Key findings:
β€’ 3 dominant approaches identified (transformer-based, graph-based, hybrid)
β€’ Gap: no work combining sparse attention with dynamic routing
β€’ 8 papers flagged as must-reads

Next step: Strategist will propose 3 research directions based on this.
Proceed? [yes / adjust / stop]
```

---

## 4. Functional Requirements

### FR-001: Session Initialization
The user creates a thread and invokes `/poly init`. A role picker is displayed. The user selects which agents to activate. Each selected agent joins the thread as a workspace member. The Coordinator always joins β€” it cannot be deselected.

Roles not selected are inactive but can be added mid-session with `/poly add [role]`.

### FR-002: Agent @mention Protocol
Any participant (human or agent) can @mention an agent by name. The Coordinator intercepts all @mentions and routes them to the appropriate agent. The mentioned agent reads the thread context, executes its task, and posts a response in the thread.

Agents may @mention other agents. The Coordinator tracks active @mention chains to prevent loops (max depth: 3).

### FR-003: Human Role Takeover
The user can take over any agent role with `/poly role [name] human`. The agent becomes dormant. Subsequent @mentions of that role name are directed to the user. The user can reinstate the agent with `/poly role [name] agent`. The agent reads the thread from the point of takeover and resumes.

### FR-004: Research State Management
The Coordinator maintains the Research State document. It is updated automatically after each checkpoint. Agents may request a Research State update mid-task if a significant discovery is made. The Research State is pinned in the thread and accessible via `/poly state`.

### FR-005: Human Checkpoint Gate
The Coordinator halts agent activity at checkpoint triggers (see Β§3.5). No agent posts to the thread until the user responds. Timeout after 24 hours defaults to "stop" to prevent runaway tasks.

### FR-006: Scout β€” Literature Search
Scout accepts a research question or topic as input. It queries Semantic Scholar and ArXiv, screens results for relevance, deduplicates, and produces a structured summary. Output format: a markdown table of papers with columns for title, year, relevance score, and a one-sentence summary. Maximum 50 papers per search. Scout @mentions Strategist when complete.

### FR-007: Strategist β€” Gap Analysis and Hypothesis Generation
Strategist reads the Scout output and the Research State. It produces up to 3 research directions, each with: a framing of the gap, a hypothesis, a proposed methodology sketch, and a confidence rating. It @mentions Critic to review before posting to the thread.

### FR-008: Critic β€” Review and Challenge
Critic reviews outputs from any agent when @mentioned. It produces a structured critique: what is strong, what is weak, what is missing, and what would make this publishable. It does not rewrite β€” it challenges. The reviewed agent is responsible for revision.

### FR-009: Scribe β€” Drafting and Citation Management
Scribe writes paper sections when @mentioned with a section name and relevant context. It reads the Research State for framing and the Scout output for citations. All citations are generated in BibTeX and appended to a running `.bib` file. Scribe @mentions Critic for a review pass before marking a section complete.

### FR-010: Coordinator β€” Orchestration
The Coordinator is always active. Responsibilities:
- Parse all @mentions and route tasks
- Track which roles are human vs. agent at any moment
- Maintain and update the Research State
- Trigger and manage checkpoints
- Detect and break @mention loops
- Post cost estimates before high-token operations
- Log all agent actions with timestamps

### FR-011: Analyst β€” Data Interpretation (on demand)
When added to a session, Analyst accepts experiment results (CSV, JSON, or pasted data), interprets them, produces summary statistics, identifies trends, and generates a findings narrative suitable for inclusion in a paper results section.

### FR-012: Artifact Export
At any point, `/poly export` produces a zip containing: the Research State document, all drafted paper sections as markdown files, the `.bib` file, and a full thread log in markdown format.

### FR-013: Multi-Platform Support
All functionality must work in Slack, Microsoft Teams, and Apache Spark (now Webex). Platform-specific features (e.g. Slack Block Kit for checkpoint UI) are enhancements, not requirements.

---

## 5. Non-Functional Requirements

**Latency:** Agent responses must begin streaming within 5 seconds of an @mention. Full responses should complete within 30 seconds for standard tasks. Literature searches may take up to 90 seconds.

**Cost transparency:** Before any operation estimated to cost more than $0.50 in LLM tokens, the Coordinator posts a cost estimate and waits for confirmation.

**Context integrity:** The Research State must never exceed 4,000 tokens to remain readable across all supported LLM contexts. The Coordinator is responsible for compression when approaching this limit.

**Reliability:** If an agent call fails, the Coordinator retries with exponential backoff (max 3 attempts, starting at 2s). If all retries fail, it posts a failure notice in the thread and marks the task as pending.

**Privacy:** Thread content and Research State are not stored beyond the session unless the user explicitly exports. No data is used for model training.

---

## 6. Technical Architecture

### 6.1 Entry Points

Polyhedra has three entry points. They are not competing interfaces β€” they are different surfaces into the same agent system. The Coordinator and agent pool do not know or care which entry point a task came from.

```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   CLI (poly)    β”‚  β”‚   MCP Server    β”‚  β”‚  Slack / Teams  β”‚
β”‚                 β”‚  β”‚                 β”‚  β”‚  / Spark thread β”‚
β”‚ poly init       β”‚  β”‚ IDE-native      β”‚  β”‚ @mention-driven β”‚
β”‚ poly search     β”‚  β”‚ tool calls from β”‚  β”‚ team session    β”‚
β”‚ poly export     β”‚  β”‚ Cursor, VS Code β”‚  β”‚ human + agents  β”‚
β”‚ local file ops  β”‚  β”‚ GitHub Copilot  β”‚  β”‚ as participants β”‚
β”‚ scripting / CI  β”‚  β”‚ Windsurf        β”‚  β”‚                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         β”‚                    β”‚                    β”‚
         β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                              β”‚ unified task interface
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                     Coordinator Service                      β”‚
β”‚       @mention parser Β· role registry Β· checkpoint engine   β”‚
β”‚       state manager Β· cost estimator Β· loop detector        β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚ dispatches tasks
          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
          β–Ό                β–Ό                β–Ό
   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
   β”‚    Scout    β”‚  β”‚ Strategist  β”‚  β”‚   Critic    β”‚
   β”‚  Scribe     β”‚  β”‚  Analyst    β”‚  β”‚  Reviewer   β”‚
   β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜
          β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                           β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                      Services Layer                          β”‚
β”‚   LLM Router (Claude / GPT / local)                         β”‚
β”‚   Paper Search (Semantic Scholar / ArXiv)                   β”‚
β”‚   Research State store Β· Artifact manager                   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```

**Entry point comparison:**

| Capability | CLI | MCP Server | Slack/Teams |
|---|---|---|---|
| Full team session | βœ“ | β€” | βœ“ |
| Single agent invocation | βœ“ | βœ“ | βœ“ |
| Human role switching | βœ“ | β€” | βœ“ |
| Local file access | βœ“ | βœ“ | β€” |
| IDE inline responses | β€” | βœ“ | β€” |
| Shared thread history | β€” | β€” | βœ“ |
| Scripting / CI automation | βœ“ | β€” | β€” |
| Checkpoint UI | terminal prompt | IDE dialog | Block Kit / Adaptive Card |
| Research State access | `/poly state` | tool call | pinned message |
| Artifact export | `/poly export` | tool call | `/poly export` |

**Shared state across entry points:** The Research State and artifacts are session-scoped, not interface-scoped. A session started in Slack can be continued via CLI (`poly resume [session-id]`) for local file operations, then returned to Slack. The Research State stays consistent across all entry points.

### 6.2 Agent Base Class

Every agent shares a common interface:

```python
class Agent:
    name: str
    role: str
    system_prompt: str          # Role definition + behavior rules
    
    async def handle(
        self,
        mention: Mention,       # Who mentioned this agent and what they said
        thread_context: list,   # Recent thread messages (capped at last N)
        research_state: dict,   # Current Research State document
    ) -> AgentResponse:
        ...
    
    async def can_handle(self, mention: Mention) -> bool:
        ...
```

### 6.3 Research State Schema

```yaml
research_state:
  goal: str                     # One-sentence research goal
  field: str                    # Domain / venue target
  gaps: list[Gap]               # Identified research gaps
  active_hypothesis: Hypothesis # Current working hypothesis
  key_papers: list[Paper]       # Up to 20 most relevant papers
  decisions: list[Decision]     # Timestamped decisions + rationale
  open_questions: list[str]     # Unresolved items
  last_updated: datetime
  version: int
```

### 6.4 Role Registry

The Coordinator maintains a role registry for each session:

```python
role_registry = {
    "scout":      RoleEntry(agent=ScoutAgent(),      held_by="agent"),
    "strategist": RoleEntry(agent=StrategistAgent(), held_by="agent"),
    "critic":     RoleEntry(agent=CriticAgent(),     held_by="human"),  # human took over
    "scribe":     RoleEntry(agent=ScribeAgent(),     held_by="agent"),
}
```

When `held_by = "human"`, @mentions of that role name are forwarded to the user via a DM or thread highlight. When the user hands back, `held_by` reverts to `"agent"` and the agent is re-initialized with the thread context from the point of takeover.

### 6.5 Tech Stack

```yaml
backend:
  language: Python 3.11+
  framework: FastAPI (webhook receiver)
  agent_framework: custom (thin layer over LLM SDK)
  llm: anthropic SDK (primary), openai SDK (optional)
  paper_search: semanticscholar, arxiv-api
  state_store: Redis (session state), SQLite (artifact persistence)

cli:
  framework: typer + rich
  entry_point: poly
  key_commands:
    - poly init          # start a new session
    - poly search        # invoke Scout directly
    - poly state         # print Research State
    - poly resume        # rejoin an existing session by ID
    - poly export        # export all artifacts
    - poly role          # take over or release an agent role
    - poly mcp           # start the MCP server

mcp_server:
  protocol: MCP (Model Context Protocol)
  compatible_ides: [Cursor, VS Code, Windsurf, GitHub Copilot]
  exposed_tools:
    - search_papers      # Scout search
    - get_research_state # read current state
    - generate_review    # Critic review of provided text
    - draft_section      # Scribe section drafting
    - add_citation       # BibTeX management

messaging_integrations:
  slack: slack-bolt
  teams: botframework-sdk
  spark: webexteamssdk

deployment:
  container: Docker
  hosting: any (Railway / Fly.io recommended for solo deployment)
  config: environment variables only, no secrets in code
```

---

## 7. User Experience

### 7.1 Session Initialization Flow

```
User:        /poly init

Coordinator: Welcome to Polyhedra. Which agents do you want on this project?
             [βœ“ Scout]  [βœ“ Strategist]  [βœ“ Critic]  [βœ“ Scribe]  [ Analyst]
             
             Are you taking any roles yourself?
             [ Scout]  [ Strategist]  [βœ“ Critic]  [ Scribe]
             
             You're playing Critic. I'll hold the other roles.
             Type your research goal to begin.

User:        I want to work on efficient transformers for long-context understanding.

Coordinator: Got it. Saving research goal.
             @Scout β€” please search for papers on efficient transformers 
             and long-context understanding.
```

### 7.2 Typical Mid-Session Exchange

```
Scout:       Found 41 papers on efficient transformers + long-context.
             Top approaches: sparse attention (18 papers), linear attention (12), 
             hybrid (11). Notable gap: sparse + linear combinations underexplored.
             @Strategist β€” ready for gap analysis.

Strategist:  Three directions stand out:
             1. Sparse-linear hybrid attention β€” high novelty, medium feasibility
             2. Adaptive context window β€” medium novelty, high feasibility  
             3. Retrieval-augmented long context β€” lower novelty, high feasibility
             @[user as Critic] β€” your assessment?

User:        Direction 1 is the only one that hasn't been beaten to death. 
             But the feasibility estimate is too optimistic β€” sparse-linear 
             integration has known training instability issues.

Strategist:  Noted. Revising direction 1 to include a training stability 
             mitigation strategy. @Scout can you find papers specifically on 
             sparse-linear training instabilities?
```

### 7.3 Checkpoint Example

```
Coordinator: ⏸ Checkpoint: Ready to begin drafting

             Hypothesis locked: Sparse-linear hybrid attention with 
             gradient norm clipping achieves 40% compute reduction 
             on sequences >8k tokens with <2% perplexity increase.
             
             Scribe is ready to draft: Introduction, Related Work.
             Estimated cost: ~$1.20
             
             Proceed? [yes / adjust scope / stop]

User:        yes

Scribe:      Starting Introduction. Will post a draft in ~2 min.
```

---

## 8. Development Roadmap

### Phase 1 β€” Foundation (Weeks 1–4)
Core infrastructure with Slack integration and two agents.

- Coordinator service: @mention parsing, role registry, checkpoint engine
- Research State: schema, CRUD, compression logic
- Scout agent: Semantic Scholar + ArXiv search, paper summary output
- Strategist agent: gap analysis, hypothesis generation
- Slack integration: webhook receiver, message posting, Block Kit checkpoint UI
- `/poly init`, `/poly state`, `/poly export` slash commands

**Exit criteria:** A user can start a Slack thread, initialize a session, have Scout search for papers, and have Strategist propose research directions with a checkpoint gate.

### Phase 2 β€” Full Team (Weeks 5–8)
Remaining core agents, human role switching, Teams integration.

- Critic agent: structured review protocol
- Scribe agent: section drafting, BibTeX management
- Human role takeover/reinstate (`/poly role`)
- Agent context handoff on role switch
- Microsoft Teams integration
- Cost estimation before high-token operations

**Exit criteria:** Full team operational in Slack and Teams. Human can take over and return any role mid-session.

### Phase 3 β€” Specialist Agents + Robustness (Weeks 9–12)
Analyst and Reviewer agents, error handling, Spark integration.

- Analyst agent: structured data interpretation, findings narrative
- Reviewer agent: venue-specific checklist review
- Retry + circuit-breaker on LLM failures
- Spark (Webex) integration
- Research State compression when approaching token limit
- Artifact export as formatted zip

**Exit criteria:** End-to-end research session from goal to exportable paper draft with full error recovery.

### Phase 4 β€” Learning + Polish (Weeks 13–16)
Preference learning, UX refinements, public release prep.

- User preference profiles: learns preferred venues, writing style, verbosity
- Checkpoint frequency tuning based on user behavior
- Polyhedra web dashboard (optional, read-only view of Research State)
- Documentation, onboarding guide, example sessions
- Open-source release on GitHub

---

## 9. Open Questions

These are unresolved design decisions to be revisited before Phase 1 begins.

**Agent identity:** Should agents have persistent names and personas (e.g. "Iris" for Scout) to make the thread feel like a real team? Benefit: stronger social presence, easier to reference. Risk: anthropomorphization may mislead users about agent reliability.

**@mention loop depth:** Max depth of 3 is a heuristic. Real research conversations may legitimately go deeper (Scout β†’ Strategist β†’ Critic β†’ Strategist β†’ Scribe). Consider task graphs instead of simple depth limits.

**Parallel vs. sequential agents:** Currently agents work sequentially (Scout finishes, then Strategist starts). Parallel execution (Scout and Strategist working simultaneously on different sub-tasks) would be faster but harder to coordinate and explain in the thread. Revisit in Phase 2.

**Research State ownership:** Currently only the Coordinator updates the Research State. Should agents be able to propose updates that the Coordinator approves? This would catch more signal but increases coordination complexity.

**Multi-human sessions:** A real research group might have multiple humans in the thread alongside agents. The role registry assumes one human per role. Multi-human support is out of scope for v3.0 but should be designed for in Phase 4.

---

## 10. Success Metrics

| Metric | Target (6 months post-launch) |
|--------|-------------------------------|
| Sessions reaching paper draft | >40% |
| Checkpoint approval rate (user proceeds vs. stops) | >70% |
| Human role takeover rate per session | >1 (users engage, not just observe) |
| Time from session init to first Scout output | <90 seconds |
| User-reported time saved vs. solo research | >50% |
| Export rate (users completing to artifact export) | >25% |