# SPECIALIST-ARCHITECTURE.md

Three-path specialist agent architecture for the OpenClaw workspace.

**Status:** Approved direction — v1 scope locked
**Last updated:** 2026-03-24
**Location:** `~/.openclaw/workspace/SPECIALIST-ARCHITECTURE.md`

---

## 1. Architecture Overview

### Design Intent

Replace the current flat delegation model (Dorian → generic worker) with specialist routing and a shared execution pool. Specialists are on-demand reasoning profiles that improve task characterization and worker contract quality. They are not persistent agents, not mini-orchestrators, and not conversational peers.

### Current State

```
Dorian (gpt-5.4, orchestrator)
  └─→ worker (gpt-5.3-codex, generic executor)
  └─→ ops-maintainer (gpt-5.4-mini, monitoring/heartbeats)
  └─→ research-intelligence (gpt-5.1-codex)
  └─→ systems-architect (gpt-5.1-codex)
  └─→ ops-manager (gpt-5.4-mini, ops specialist)
```

### Target State — Specialist Routing with Shared Execution Pool

```
┌──────────────────────────────────────────────────────────┐
│  DORIAN (gpt-5.4) — sole orchestrator and normalizer     │
│                                                          │
│  Classifies request → selects dispatch path:             │
│                                                          │
│  Path A ──→ Dorian handles directly                      │
│  Path B ──→ Dorian constructs worker contract → Worker   │
│  Path C ──→ Specialist reasons about task → Worker       │
│                                                          │
├──────────────────────────────────────────────────────────┤
│  SPECIALISTS (on-demand reasoning profiles)              │
│                                                          │
│  v1: Systems Architect | Research Intelligence | Ops Mgr │
│                                                          │
│  Specialist receives task from Dorian                    │
│  Specialist characterizes scope and complexity           │
│  Specialist recommends worker model (within policy)      │
│  Specialist constructs worker contract                   │
│  Specialist validates worker output                      │
│  Specialist returns completion contract to Dorian        │
│                                                          │
├──────────────────────────────────────────────────────────┤
│  SHARED WORKER POOL (model selected per task)            │
│                                                          │
│  gpt-5.4 | gpt-5.3-codex | gpt-5.4-mini | spark        │
│  Local fallback: qwen2.5 | glm-4.7-flash (Ollama)      │
│                                                          │
│  Worker receives contract → executes → returns output    │
│  No direct user communication                            │
│                                                          │
├──────────────────────────────────────────────────────────┤
│  Completion contracts flow upward:                       │
│  Worker → Specialist → Dorian → User                     │
│  Worker → Dorian → User (Path B)                         │
└──────────────────────────────────────────────────────────┘

Separate, unchanged:
  ops-maintainer (gpt-5.4-mini) — heartbeats, monitoring
  generic worker — backward compatible during rollout
```

### Invariant Rules

1. Dorian is the single normalization layer. No specialist or worker surfaces output directly to the user in main session.
2. Specialists have scoped dispatch authority within their domain, bounded by Dorian-defined routing policy.
3. Every worker invocation uses the universal worker contract format.
4. Risk-sensitive actions (auth, financial, irreversible, external-facing) are retained by Dorian regardless of specialist routing.
5. Prefer event-driven or heartbeat-batched patterns over polling loops.
6. Latency override: Dorian may execute directly (Path A) or dispatch directly to a worker (Path B) when specialist reasoning adds no material value.
7. No specialist may maintain its own long-lived conversational memory outside the canonical Dorian/main session and approved workspace files. Specialists are stateless and on-demand.

---

## 2. Dispatch Paths

Every incoming request follows one of three paths. Path B is the default for execution tasks. Path C is the escalation when domain reasoning materially improves output.

### Path A — Dorian Direct

**When:** Task is conversational, strategic discussion, clarification, classification, or small/single-step/low-risk where delegation overhead exceeds task cost.

**Flow:** `User → Dorian → User`

### Path B — Worker Dispatch

**When:** Task is execution-heavy but domain reasoning is trivial or unnecessary.

**Flow:** `User → Dorian → [constructs contract] → Worker → Dorian → User`

### Path C — Specialist Dispatch

**When:** Domain reasoning materially improves output quality.

**Flow:** `User → Dorian → Specialist → [constructs contract] → Worker → Specialist → Dorian → User`

**Routing threshold — use Path C when any of the following are true:**
- Task requires domain-specific decomposition to construct an effective contract
- Task scope is ambiguous and benefits from specialist analysis before execution
- Task type has historically produced better results with specialist reasoning
- Sequential specialist pairing is needed (e.g., Research → Communications)

### Path Selection Heuristic

```
1. Is the task conversational, strategic, or clarification?
   YES → Path A (Dorian direct)

2. Is the task small, single-step, and low-risk?
   YES → Path A (latency override)

3. Does the task involve risk-sensitive action?
   YES → Dorian retains control (Path A or B with CONFIRM gate)
         Specialist may be consulted read-only if needed

4. Can Dorian construct an adequate worker contract directly?
   YES → Path B (worker dispatch)

5. Would specialist reasoning materially improve the contract?
   YES → Path C (specialist dispatch)
         Match domain:
         ├─ Automation / config / integration → Systems Architect
         ├─ Research / comparison / analysis → Research Intelligence
         ├─ Action items / SOPs / process    → Ops Manager
         └─ No clear match → Path B

6. Does the task require sequential pairing?
   YES → Path C with queued specialists
```

---

## 3. Specialist Registry — v1

v1 includes three specialists. Communications, Finance Modeling, and Theological Reflection are deferred to v2 pending demonstrated need.

### 3.1 Systems Architect

| Field | Value |
|---|---|
| **Domain** | Automation design, Notion workflows, OpenClaw configuration, integrations, infrastructure |
| **Trigger conditions** | Config generation, workflow design, integration setup, heartbeat design, pipeline architecture, OpenClaw CLI operations |
| **Model routing range** | Floor: `gpt-5.4-mini` / Ceiling: `gpt-5.4` |
| **Default recommendation** | `gpt-5.3-codex` for config and code generation; `gpt-5.4` for architecture decisions |
| **Sequential pairing** | Ops → Systems (when process requires automation backing) |
| **Special constraint** | Auth/token modifications retained by Dorian; Systems Architect may draft but not execute |

### 3.2 Research Intelligence

| Field | Value |
|---|---|
| **Domain** | Comparisons, research, document analysis, tool evaluation, competitive analysis |
| **Trigger conditions** | Evaluating options, analyzing documents, structured comparison, evidence gathering |
| **Model routing range** | Floor: `gpt-5.4-mini` / Ceiling: `gpt-5.4` |
| **Default recommendation** | `gpt-5.3-codex` for structured parsing and tabulation; `gpt-5.4` for nuanced evaluation |
| **Sequential pairing** | Research → Communications (deferred to v2; Dorian handles comms normalization in v1) |

### 3.3 Ops Manager

| Field | Value |
|---|---|
| **Domain** | Action items, SOPs, meeting outputs, process execution, checklists, status reporting |
| **Trigger conditions** | Task tracking, meeting follow-up, operational procedure, process documentation |
| **Model routing range** | Floor: `gpt-5.3-codex-spark` / Ceiling: `gpt-5.4` |
| **Default recommendation** | `gpt-5.4-mini` for checklists and status; `gpt-5.4` for multi-dependency SOPs |
| **Sequential pairing** | Ops → Systems (when SOP requires automation) |

### 3.4 Deferred Specialists (v2)

| Specialist | Domain | Deferral Rationale |
|---|---|---|
| **Communications** | Human-facing written communication | Dorian handles comms adequately in v1 |
| **Finance Modeling** | ROI, pricing, margin math, sensitivity | Low current frequency; doesn't justify routing overhead yet |
| **Theological Reflection** | Ethical tension, leadership posture, values framing | Advisory by nature; informal reasoning mode only |

---

## 4. Model Routing Governance

### 4.1 Principle

Quality first, cost efficiency second. Specialists recommend within policy; Dorian enforces system-level cost discipline.

### 4.2 Governance Model

1. **Dorian defines the routing policy.** The model routing table sets a floor and ceiling per specialist per task type. Single source of truth.
2. **Specialists recommend a model** after characterizing the task.
3. **Recommendations within range stand** without review.
4. **Escalations above ceiling require Dorian approval** with justification.
5. **Dorian may override downward** if system-level constraints require it.

### 4.3 Model Routing Table

| Specialist | Task Type | Floor | Default | Ceiling |
|---|---|---|---|---|
| **Systems Architect** | Config generation, scripts, automation code | `gpt-5.4-mini` | `gpt-5.3-codex` | `gpt-5.3-codex` |
| **Systems Architect** | Architecture decisions, tradeoff analysis | `gpt-5.4-mini` | `gpt-5.4` | `gpt-5.4` |
| **Research Intel** | Document analysis, structured comparison | `gpt-5.4-mini` | `gpt-5.3-codex` | `gpt-5.3-codex` |
| **Research Intel** | Nuanced evaluation, subjective analysis | `gpt-5.3-codex` | `gpt-5.4` | `gpt-5.4` |
| **Ops Manager** | Checklists, status updates, simple SOPs | `gpt-5.3-codex-spark` | `gpt-5.4-mini` | `gpt-5.4-mini` |
| **Ops Manager** | Multi-dependency SOPs, complex process | `gpt-5.4-mini` | `gpt-5.4` | `gpt-5.4` |

### 4.4 Context Window Override

For tasks requiring ingestion of large documents (>80k tokens), prefer `gpt-5.3-codex-spark` (125k context) or local `glm-4.7-flash` (202k context) regardless of routing table defaults. Hard override based on technical constraint.

### 4.5 Fallback Routing

| Primary Model | Fallback 1 | Fallback 2 (Local) |
|---|---|---|
| `gpt-5.4` | `gpt-5.3-codex` | `qwen2.5` (Ollama) |
| `gpt-5.3-codex` | `gpt-5.4-mini` | `qwen2.5` (Ollama) |
| `gpt-5.4-mini` | `gpt-5.3-codex-spark` | `glm-4.7-flash` (Ollama) |
| `gpt-5.3-codex-spark` | `gpt-5.4-mini` | `glm-4.7-flash` (Ollama) |

Fallback 1 is automatic. Fallback 2 (local Ollama) requires Dorian approval. Circuit breaker: 3 consecutive failures halt and return failure contract — no auto-retry.

---

## 5. Worker Contract Spec

### 5.1 Universal Contract Format

```yaml
worker_contract:
  task_id: ""
  origin_thread: ""
  objective: |
    Clear, single-sentence statement of what the worker must accomplish.
  scope: |
    Boundaries of the task. What is in scope and what is explicitly excluded.
  constraints:
    - Constraint 1
    - Constraint 2
  permissions:
    filesystem: read|write|none
    network: none|local|external
    notion: read|read-write|none
    telegram: none|read|send
    shell: restricted|full
    git: read|commit|push|none
  model_recommendation: ""
  rollback_required: false
  rollback_plan: ""
  output: |
    Description of expected deliverable format and location.
  done: |
    Definition of done — what must be true for the task to be complete.
```

### 5.2 Specialist Extension Points

**Systems Architect:**
```yaml
systems_context:
  target_system: ""        # openclaw | notion | cron | integration name
  config_paths: []         # Files that may be read or modified
```

**Research Intelligence:**
```yaml
research_context:
  evaluation_criteria: []  # Ordered list of comparison dimensions
  source_constraints: []   # Required or excluded source types
  output_format: ""        # table | narrative | scorecard
```

**Ops Manager:**
```yaml
ops_context:
  related_tasks: []        # Notion task IDs
  sop_reference: ""        # Path to relevant SOP if exists
  status_field_target: ""  # Notion status value to set on completion
```

---

## 6. Tool Access Boundaries

### 6.1 Specialist Tool Access

**Allowed — direct (no worker contract needed):**
- Read local workspace files (`~/.openclaw/workspace/` and subdirectories)
- Read internal metadata (agent config, contract templates, routing tables)

**Not allowed — must go through worker contract:**
- All connector operations (Notion, Telegram, external APIs) including reads
- All filesystem writes
- All shell execution (except bounded worker dispatch — see specialist contracts)
- All git operations
- All network operations

**Rationale:** Every external interaction goes through a contract. Clean audit boundary — when something fails, trace exactly what was attempted by reading the contract log.

### 6.2 Worker Tool Access

Workers operate within the permissions defined in their contract only. No implicit permissions. If a permission isn't listed in the contract, the worker doesn't have it.

---

## 7. Completion and Failure Contracts

### 7.1 Worker Completion Contract

```
Completion Contract
Task ID: [from worker contract]
Done: [what was accomplished]
Findings: [results, data, or output summary]
Decision needed: [any blocking decision for Dorian or user]
Next step: [recommended follow-up]
```

### 7.2 Specialist Completion Contract (Path C only)

```
Specialist Completion
Specialist: [name]
Task ID: [from worker contract]
Worker model used: [model]
Iterations: [number of worker dispatches for this task]
Done: [what was accomplished]
Findings: [results, data, or output summary]
Domain assessment: [specialist's evaluation of output quality and completeness]
Decision needed: [any blocking decision]
Next step: [recommended follow-up]
Risks surfaced: [if any]
```

### 7.3 Failure Contract

```
Failure Contract
Specialist: [name, or "Dorian" if Path B]
Task ID: [from worker contract]
Worker model attempted: [model]
Failure type: timeout | error | capability_gap | permission_denied
Attempts: [count]
Error summary: [what went wrong]
Partial output: [any usable partial results]
Recommended action: [retry with different model | escalate to Dorian | surface to user]
```

### 7.4 Dorian Visibility

**Dorian always sees:** every completion and failure contract, which specialist handled the task, which worker model was used, how many iterations occurred, any risks surfaced.

**Dorian filters before presenting to user:** internal iteration details, model selection rationale, specialist-internal reasoning, worker-level error logs (summarized into actionable findings).

### 7.5 Circuit Breaker

Three consecutive worker dispatch failures within a single task → halt and return failure contract. Dorian presents to user and does not auto-retry.

---

## 8. Failure and Fallback Rules

### 8.1 Worker Failure

**Timeout:** Retry once with same model → fall to Fallback 1 → return failure contract if still failing.

**Error:** Specialist inspects. If recoverable (bad prompt, scope too broad), refine contract and re-dispatch. If non-recoverable (capability gap, missing permissions), return failure contract.

### 8.2 Specialist Failure

If specialist cannot reason about task: return to Dorian with reclassification request. Dorian may reroute to different specialist, downgrade to Path B, or handle directly.

### 8.3 Dorian Failure Handling

1. Assess severity: blocking or degraded-acceptable?
2. If degraded-acceptable: use partial output, note limitations to user.
3. If blocking: inform user with what is known, what failed, and recommended next step.
4. Never present raw error output — always normalize.

---

## 9. Relationship to Existing Workspace

### 9.1 Backward Compatibility

Generic worker continues functioning for tasks not yet routed through a specialist. Path B is identical to current system behavior. No existing capability removed during rollout.

### 9.2 ops-maintainer Independence

`ops-maintainer` (gpt-5-mini) remains a separate lightweight agent for heartbeats and monitoring. Not part of the specialist routing system. Ops Manager specialist is on-demand for substantive task work. Distinct agents, distinct purposes, distinct models.

### 9.3 Document Relationships

| Document | Relationship |
|---|---|
| `AGENTS.md` | Parent document. This spec extends the Executive Hierarchy Extension and Delegation Framework. |
| `OPERATING-MODE.md` | Canonical behavior contract. Completion Contract format, two-lane model, and latency SLA apply unchanged. |
| `IDENTITY.md` | Defines Dorian's role and synthesis standards. This spec does not modify Dorian's identity. |
| `SOUL.md` | Core operating principles. All specialist and worker behavior is subordinate to these rules. |
| `WORKER-CONTRACT.md` | This spec supersedes it with the universal contract format in Section 5. Migration required: update `~/.openclaw/workspace-worker/WORKER-CONTRACT.md`. |

---

## 10. Implementation Plan

| Phase | Description |
|---|---|
| **Phase 1** | **Contract Discipline** — Formalize universal worker contract (Section 5) and completion/failure contract formats (Section 7). Update `WORKER-CONTRACT.md`. Delivers value immediately on Path B. |
| **Phase 2** | **Routing Policy** — Implement three-path dispatch model (Section 2) and model routing table (Section 4) in Dorian's operating logic. Update `AGENTS.md` delegation framework to reference this document. |
| **Phase 3** | **Systems Architect Specialist** — First Path C specialist. Highest current usage, clearest domain boundary. |
| **Phase 4** | **Research Intelligence Specialist** — Validates multi-specialist routing model. |
| **Phase 5** | **Ops Manager Specialist** — Validates sequential pairing (Ops → Systems). |
| **Phase 6** | **Evaluate v2 Specialists** — Communications, Finance Modeling, Theological Reflection based on actual usage patterns and demonstrated need. |

---

## 11. Open Questions

### Resolved

| Question | Resolution |
|---|---|
| Specialist persistence | On-demand. No persistent specialist sessions in v1. |
| Worker pool model | Shared pool with model selection at dispatch. |
| Model routing ownership | Dorian defines policy table; specialists recommend within range; escalations require Dorian approval. |
| Specialist tool access | Local workspace reads only. All connector operations through worker contracts (bounded shell exception for worker dispatch). |
| ops-maintainer relationship | Separate agent. Not part of specialist routing. |
| v1 specialist scope | Systems Architect, Research Intelligence, Ops Manager only. |
| Specialist memory | No long-lived memory outside canonical workspace files. |
| Contract delivery mechanism | Specialist spawns worker via `openclaw agent --agent worker --message "<contract>" --json`. |
| Task ID generation | Dorian generates at classification time. |
| Contract logging | `~/.openclaw/workspace/contracts/YYYY-MM-DD/` with one file per task_id. |