Openclaw Agent Blueprint Web Runtime Compat

# OpenClaw Web Agent Blueprint Compatibility

Status: accepted  
Date: 2026-03-10

## Purpose

This document defines how the web app represents agent organization modes while remaining compatible with the current `pi_agent_rust` runtime direction.

The runtime remains authoritative for executable structure. The web app may provide richer UX presets, but runtime payload compatibility takes priority whenever the two differ.

## Current Scope

The first implementation applies to the curated `website_development_system` template only.

Web-visible blueprint modes:

1. `maozhua_auto`
2. `three_provinces_six_ministries`
3. `raci_rapid`
4. `squad_matrix`

These are UX presets, not required runtime-native enums.

## Compatibility Rule

The web app stores:

- `templateId`
- `blueprintModeId`
- localized presentation metadata for UI rendering

The runtime payload uses a normalized generic structure:

- `teamBlueprint.groups[]`
- `teamBlueprint.roles[]`
- `teamBlueprint.edges[]`
- `teamBlueprint.strategy`
- `teamBlueprint.coordinationStyle`
- `teamBlueprint.decisionModel`
- `teamBlueprint.orchestrationHints`

If the client ignores `blueprintModeId` or any advisory metadata but accepts the normalized blueprint fields, launch should still succeed.

## Emitted Payload Shape

Website workflow launches include:

```json
{
  "workflowType": "website_development",
  "templateId": "website_development_system",
  "blueprintModeId": "maozhua_auto",
  "stage": "strategy_brief",
  "siteProjectId": "sys_xxx",
  "teamBlueprint": {
    "schemaVersion": "web.blueprint.v1",
    "templateType": "website_development",
    "blueprintModeId": "maozhua_auto",
    "strategy": "automatic",
    "coordinationStyle": "adaptive_routing",
    "decisionModel": "runtime_directed",
    "groups": [],
    "roles": [],
    "edges": [],
    "orchestrationHints": {}
  },
  "input": {}
}
```

## Why This Mapping Exists

The current client roadmap uses concepts like:

- `SystemProfile`
- `Team Blueprint`
- template-first system creation

But the client may tighten its exact accepted schema over time.

The web app therefore does not require the client to understand branded modes like `three_provinces_six_ministries` directly. The web translates those modes into a generic blueprint payload that is easier to keep compatible.

## Template Rules

Templates declare:

- supported blueprint modes
- recommended blueprint mode
- default outputs
- launch hints

Current release rule:

- curated templates only
- no arbitrary GitHub URL template import
- no non-curated external format ingestion

## Fallback Behavior

If the runtime does not support some metadata:

1. ignore `blueprintModeId`
2. ignore unknown role tags
3. continue using the normalized role/group/edge structure

If runtime validation later becomes stricter, the only required update point should be the web-side mapping in:

- `src/lib/agent-blueprint.ts`

## Adding a New Blueprint Mode

To add a new mode safely:

1. add the mode to `blueprintModeIds`
2. define localized UI metadata
3. define groups, role tags, and edges
4. verify the generated `teamBlueprint` still matches client-supported generic fields
5. expose the mode from the curated template catalog only after validation

## Non-goals for This Phase

Not supported in this phase:

- runtime-native named blueprint enums
- arbitrary external GitHub template import
- direct execution semantics tied to branded organizational labels

If the client later introduces a stricter or officially supported format, that format wins and the web layer must adapt to it.