Plan Orchestration Overview
How Trovella coordinates multi-step research plans through state machines, branching, stall detection, and a pull-based execution loop.
Plan orchestration is the coordination layer that keeps multi-step research plans on track. It manages the lifecycle of plans and their individual steps through two interlocking state machines, evaluates branching conditions to alter execution flow, detects stalled steps, and tracks progress -- all backed by PostgreSQL for durability across sessions.
The plan engine lives in packages/mcp/src/plan-engine/ as pure functions with no database access and no framework dependencies. This makes the state machine logic fully testable in isolation. The MCP tool handlers in packages/mcp/src/tools/ wire these pure functions to database mutations inside withTenantContext transactions.
Core Concepts
Pull-based execution
The AI platform (Claude Code, ChatGPT) drives execution, not the server. This is the opposite of push-based orchestration frameworks like LangGraph. The loop:
- AI platform calls
get_next_step-- server transitions next pending step toin_progress, returns instructions - AI platform does reasoning, web searches, synthesis
- AI platform calls
submit_step_result-- server validates, evaluates branching, advances state machine - Repeat until
{ status: "plan_complete" }
The server never calls the AI platform. It only responds to tool calls. This is what makes the economics work: all LLM reasoning happens in the user's subsidized subscription.
Durability through PostgreSQL
All plan state lives in PostgreSQL, not in memory. Plans survive session disconnects, browser closes, and server restarts. A user can start a research plan in one Claude Code session, close their laptop, and resume in a new session by calling get_research_context followed by get_next_step.
Failed steps do not fail the plan
This is the most important non-obvious invariant. When a step fails (via modify_plan with fail_step action), the plan continues to the next pending step. Failed steps are treated like skipped steps. Plans only fail through two paths: an explicit fail branching action, or a user reject decision during review.
Pages in This Topic
State Machines
The plan and step finite state machines -- every valid state, every valid transition, the derivePlanStatus function that computes plan state from step states, and the invariants that protect the system.
Branching
Conditional execution flow: how branching conditions are defined at plan creation, evaluated after each step completion, and how they trigger skip_to, add_steps, fail, or continue actions.
Stall Detection
How the system identifies steps stuck in in_progress too long, the 30-minute default threshold, and how stall information surfaces through get_plan_status.
Execution Loop
The end-to-end flow from plan creation through step execution to completion, including the human-in-the-loop review cycle and cross-session resume.
Progress Tracking
How get_plan_status computes progress percentage, surfaces stall warnings, and returns the derived plan status alongside step breakdowns.
ADR-010: MCP-First Architecture + Plan Engine
The architectural decision record covering why Trovella uses an MCP-first architecture with a custom plan engine instead of server-side LLM orchestration or off-the-shelf workflow frameworks.
Key Files
| File | Purpose |
|---|---|
packages/mcp/src/plan-engine/plan-transitions.ts | Plan and step state types, transition validation, derivePlanStatus |
packages/mcp/src/plan-engine/branching.ts | Safe condition expression evaluator, branch action resolution |
packages/mcp/src/plan-engine/stall-detection.ts | detectStalledSteps, isPlanStalled |
packages/mcp/src/plan-engine/index.ts | Public API re-exports |
packages/mcp/src/tools/create-research-plan.ts | Plan creation with steps, branching, skill-execution linkage |
packages/mcp/src/tools/get-next-step.ts | Step advancement, plan state transition |
packages/mcp/src/tools/submit-step-result.ts | Step completion, branching evaluation, plan status derivation |
packages/mcp/src/tools/modify-plan.ts | Add/remove/reorder steps, fail stuck steps |
packages/mcp/src/tools/get-plan-status.ts | Progress, stall warnings, step breakdown |
packages/mcp/src/tools/request-user-review.ts | Pause plan for user checkpoint |
packages/mcp/src/tools/submit-user-decision.ts | Resume after user approve/reject/modify/skip |
Cross-Topic References
- Data & Storage -- Schema Design -- the
research_plan,plan_step, andplan_branching_conditiontable definitions - Data & Storage -- Query Patterns -- how plan queries use
withTenantContextfor RLS enforcement - Identity & Access -- Tenant Isolation -- how plan data is isolated per organization
- Search & Retrieval -- how
store_researchtriggers the indexing pipeline - Application -- Admin Dashboard -- Research Plans View -- the admin UI for monitoring plans
Lifecycle Tracking
How skill executions are persisted, tracked, and queried -- the skill_execution table, log_skill_execution MCP tool, tRPC admin router, and metadata conventions.
Plan and Step State Machines
The two interlocking finite state machines that govern research plan and step lifecycles, including every valid state, transition, and the derivePlanStatus function.