# Orchestrator

## The Orchestrator — Jarvis

Jarvis is the central intelligence of Assemble. Like Tony Stark’s AI assistant, Jarvis doesn’t do the work — he figures out **who** should do it, **when**, in **what order**, and with **what context**.

## How Jarvis works

Every request goes through Jarvis first. His process:

1. **Receive** the user’s request  
2. **Classify** the domain (dev, marketing, SEO, product, security, ops…)  
3. **Assess complexity** (TRIVIAL, MODERATE, or COMPLEX)  
4. **Match a workflow** or compose an ad-hoc one  
5. **Execute** — activate agents sequentially with context injection  
6. **Verify** — check that each agent produced their expected outputs  
7. **Report** — deliver a summary with all deliverables

## Complexity assessment

Jarvis evaluates every request against three complexity levels:

### TRIVIAL

- Simple question or single-domain task  
- One agent suffices  
- Direct answer, no formal workflow

**Example**: “What’s the best way to handle auth tokens?”  
**Route**: `@bruce-banner` answers directly.

### MODERATE

- Clear task spanning 2-3 agents  
- No formal spec needed  
- Sequential execution with deliverables

**Example**: “/bugfix the search endpoint returns stale results”  
**Route**: `@bruce-banner` diagnoses + fixes, `@hawkeye` writes regression test.

### COMPLEX

- Multi-domain, high-stakes, or ambitious task  
- Requires specification, planning, and task breakdown  
- Applies the **Spec-Driven methodology**

**Example**: “/feature add real-time collaborative editing”  
**Route**: Full Spec-Driven flow (see below).

## The Spec-Driven methodology

For COMPLEX tasks, Jarvis enforces a structured 5-phase approach:

### Phase 1 — SPECIFY (`@professor-x`)

Produces `spec.md` containing:

- Objective and success criteria  
- Constraints and assumptions  
- User stories and acceptance criteria  
- Out-of-scope items

**User validation required before proceeding.**

### Phase 2 — PLAN (`@tony-stark`)

Produces `plan.md` containing:

- Architecture decisions  
- Technical choices with rationale  
- Agents involved and their sequence  
- Risk assessment

**User validation required before proceeding.**

### Phase 3 — TASKS (`@captain-america`)

Produces `tasks.md` containing:

- Task breakdown with estimates  
- Dependencies between tasks  
- Priority ordering  
- Acceptance criteria per task

**User validation required before proceeding.**

### Phase 4 — IMPLEMENT (Board Execution)

For **COMPLEX** workflows, Captain America turns `tasks.md` into `_board.yaml`, then the Board Execution engine runs tickets in parallel through `implement → review → test → done`.

Key properties:

- Automatic WIP limits keep implementation, review, and test stages balanced  
- Dependency resolution ensures blocked tickets wait until upstream work is `done`  
- Ticket-specific context injection keeps each agent focused on its own scope and acceptance criteria  
- Simpler workflows can still stay on the linear implementation path when a board would add unnecessary overhead

See the [Board Execution reference](/content/docs/reference/board-execution/index.html) for the full board format and execution rules.

### Phase 5 — CLOSE (Jarvis)

Produces `_quality.md` with:

- What was delivered  
- What was validated  
- Remaining risks  
- Lessons learned

## Routing intelligence

Jarvis uses **keyword matching** and **domain classification** to route requests:

| Keywords | Agent | Domain |
| --- | --- | --- |
| API, backend, server, endpoint | `@bruce-banner` | Backend |
| UI, frontend, React, components | `@spider-man` | Frontend |
| test, QA, regression, E2E | `@hawkeye` | Testing |
| security, vulnerability, audit | `@punisher` | Security |
| SEO, crawl, indexation | `@black-widow` | Technical SEO |
| campaign, marketing, GTM | `@star-lord` | Marketing |
| architecture, scalability | `@tony-stark` | Architecture |

The full routing table covers all 34 agents. When keywords overlap, Jarvis selects the most relevant agent based on the full context.

## Context injection

Before each agent works, Jarvis injects context:

1. **Workflow context**: which workflow, which step (N/total), what comes before and after  
2. **Input files**: deliverables from previous steps that the agent should read  
3. **Expected outputs**: what files the agent must produce  
4. **Constraints**: stay consistent with previous agents’ work, don’t repeat

This ensures agents build on each other’s work rather than starting from scratch.

## The manifest

During workflow execution, Jarvis maintains `_manifest.yaml`:

```yaml
workflow: feature-development

started: 2026-03-21T10:00:00Z

status: in_progress

steps:

- id: spec

agent: professor-x

status: completed

started: 2026-03-21T10:00:00Z

completed: 2026-03-21T10:02:30Z

outputs:

- spec.md

- id: plan

agent: tony-stark

status: in_progress

started: 2026-03-21T10:02:35Z

outputs: []
```

This is the source of truth for the workflow’s state.