> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scriptonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Orchestration

> Multi-agent system design, roles, communication, and coordination.

## Multi-Agent System Design

Scriptonia uses **specialized AI agents** driven by LLM calls (OpenRouter). Two modes:

1. **Sequential (stages 1–3):** One agent per stage — IdeaProcessor → IntentAnalyzer → PlatformSelector.
2. **Parallel (execution):** Multiple execution agents (ProductManager, FrontendDev, BackendDev, DevOpsEngineer, ToolManager) generate files in parallel based on platform templates.

Orchestration is implemented in `lib/openai.ts` (`executeX402Workflow`) and `lib/platform-templates.ts` (`generatePlatformDeliverables`). The X402 workflow and A2A helpers in `lib/x402.ts` and `lib/a2a.ts` support coordination and future extensions.

***

## Agent Roles and Responsibilities

Defined in `lib/x402.ts` as `AGENT_ROLES`:

| Agent                | Stage               | Responsibility                                                                     |
| :------------------- | :------------------ | :--------------------------------------------------------------------------------- |
| **CEO**              | idea\_input         | Entry; routes to X402Agent and other agents (conceptual in current flow).          |
| **X402Agent**        | execution           | Orchestrator for X402 execution, payment, platform.                                |
| **IdeaProcessor**    | idea\_input         | Analyzes idea → `analysis`, `clarifying_questions`.                                |
| **IntentAnalyzer**   | intent\_analysis    | Refines idea + answers → `refined_requirements`.                                   |
| **PlatformSelector** | platform\_selection | Maps requirements → `platform_options`, `recommended`.                             |
| **PaymentValidator** | payment\_processing | Validates wallet/balance (in `lib/solana` and payment API).                        |
| **ProductManager**   | execution           | PRD, PLAN, requirements; coordinates with Frontend/Backend, ToolManager.           |
| **FrontendDev**      | execution           | UI, pages, components; coordinates with Backend, ToolManager.                      |
| **BackendDev**       | execution           | APIs, DB, services; coordinates with Frontend, AIEngineer, ToolManager.            |
| **AIEngineer**       | execution           | AI pipelines, RAG, prompts (in `AGENT_ROLES`; execution file assignment may omit). |
| **DevOpsEngineer**   | execution           | Infra, CI/CD, deployment; coordinates with ToolManager.                            |
| **ToolManager**      | execution           | GitHub, meta, export, external services; coordinates with all.                     |

***

## Communication Patterns

### Sequential (Idea → Intent → Platform)

* **IdeaProcessor:** Input: `idea`. Output: `analysis`, `clarifying_questions`. No inter-agent call.
* **IntentAnalyzer:** Input: `idea`, `answers`. Output: `refined_requirements`. No inter-agent call.
* **PlatformSelector:** Input: `refined_requirements`. Output: `platform_options`, `recommended`. No inter-agent call.

Data flows via `WorkflowContext` (DB or in-memory). Each step is a single LLM request.

***

### Parallel (Execution)

* **File–agent mapping:** `getAgentForFile` in `lib/platform-templates.ts`:
  * `PRD`, `PLAN`, `requirements` → **ProductManager**
  * `frontend`, `components`, `pages` → **FrontendDev**
  * `backend`, `api`, `database` → **BackendDev**
  * `infra`, `deployment`, `ci_cd` → **DevOpsEngineer**
  * `github`, `meta`, `export` → **ToolManager**
* **Coordination:** `generateFileContentWithAgent` receives `existingDeliverables` and `workflowContext` (idea, analysis, answers, platform, payment). Agent-specific system prompts and “related files” from other agents are included so output stays consistent.
* **Parallelism:** Files are grouped by agent; agents run in parallel (`Promise.all`). Within an agent, files are processed in batches (e.g. 5) with small delays to reduce duplicate content and respect rate limits.

***

## Coordination Mechanisms

1. **WorkflowContext** — Single source of truth for idea, analysis, answers, `refinedRequirements`, `platformOptions`, `selectedPlatform`, `paymentDetails`, `supabaseIntegration`. Passed into `generatePlatformDeliverables` and `generateFileContentWithAgent`.
2. **Platform templates** — `getWebsiteTemplate`, `getWebAppTemplate`, `getAndroidTemplate`, `getIOSTemplate` define `folderStructure` and `techStack`. `generatePlatformDeliverables` walks the tree, assigns each file to an agent, and runs generation.
3. **Agent system prompts** — In `generateFileContentWithAgent`, each execution agent has a short system prompt (e.g. “Coordinate with FrontendDev and BackendDev”) so generated specs and contracts stay aligned.
4. **A2A (optional)** — `lib/a2a.ts` provides `sendA2ARequest`, `sendA2AResponse`, `shareA2AData`, `sendA2ANotification`, and `A2AWorkflowIntegration`. Used for tests and can be used for richer agent-to-agent calls during execution.
5. **Review step** — `reviewDeliverables` in `openai.ts` checks structure and completeness and sets `review_passed` / `review_issues` on the execution result.
6. **Deduplication** — `deduplicateContent` regenerates content for duplicate deliverables to improve uniqueness.