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% |
|