Webgpu Agents Pipeline Orchestrator

WebGPU Pipeline Orchestrator

Sequence a correct end-to-end WebGPU setup and route every step to the right detailed skill. Baseline: WebGPU 1.0-stable (Chrome 113+, Safari 26+, Firefox 141+).

Quick Reference

The canonical setup sequence. ALWAYS run these steps in this exact order. Each step depends on every step above it.

Steps 1 to 5 run ONCE per application. Steps 7 to 12 run ONCE at load time. Steps 13 to 15 run every frame with a fresh encoder.

Decision Tree

What is the workload?
├─ Draw pixels to a canvas → RENDER PATH
│    1-5 init  →  6 configure canvas  →  7 shader module (vertex + fragment)
│    →  8 bind group layouts  →  9 pipeline layout  →  10 createRenderPipeline
│    →  11 vertex/index/uniform buffers + textures  →  12 bind groups
│    →  per frame: 13 encoder → 14 beginRenderPass → 15 finish + submit
│
├─ Run a GPGPU kernel, no canvas → COMPUTE PATH
│    1-5 init  →  (skip 6, no canvas)  →  7 shader module (compute)
│    →  8 bind group layouts  →  9 pipeline layout  →  10 createComputePipeline
│    →  11 storage buffers + readback staging buffer  →  12 bind groups
│    →  13 encoder → 14 beginComputePass + dispatchWorkgroups → 15 finish + submit
│    →  await onSubmittedWorkDone, then mapAsync the staging buffer
│
└─ Both (compute feeds render) → run COMPUTE PATH then RENDER PATH
     in the SAME encoder; pass ordering inside one submit guarantees the
     compute write completes before the render read.

Use "auto" layout or an explicit GPUPipelineLayout?
├─ One pipeline, resources not shared → layout: "auto"
│    bind groups come from pipeline.getBindGroupLayout(i), bound to THAT pipeline only
└─ Resources shared across pipelines → explicit createPipelineLayout
     ALWAYS explicit when two pipelines must share a bind group.

Which buffer usage flags? (see Skill Routing Map and references/methods.md)
├─ Mesh positions → VERTEX | COPY_DST
├─ Index data → INDEX | COPY_DST
├─ Per-frame matrices → UNIFORM | COPY_DST
├─ Large random-access compute data → STORAGE | COPY_DST
├─ Indirect draw/dispatch args → INDIRECT | COPY_DST
└─ GPU to CPU readback → MAP_READ | COPY_DST   (NEVER add STORAGE here)

Core Patterns

Pattern 1: ALWAYS negotiate limits and features before creating any resource

Steps 1 to 3 run before step 11. requestDevice() validates API calls against the negotiated limits, not the adapter's full limits. Creating a buffer or texture before the device exists is impossible; planning sizes before reading adapter.limits produces resources that fail validation on lower-tier hardware. ALWAYS feature-detect: requiredFeatures: adapter.features.has("shader-f16") ? ["shader-f16"] : []. Route to webgpu-core-limits-features.

Pattern 2: ALWAYS build bind group layouts before the pipeline

The pipeline layout (step 9) consumes the bind group layouts (step 8), and the pipeline (step 10) consumes the pipeline layout. NEVER call createRenderPipeline or createComputePipeline before its GPUBindGroupLayout objects exist. With layout: "auto" the pipeline generates implicit layouts, but those layouts are NOT reusable across pipelines. Route to webgpu-syntax-bind-groups and webgpu-core-pipeline-architecture.

Pattern 3: ALWAYS keep @group/@binding, visibility, and formats consistent across three places

A binding is defined in THREE places that MUST agree exactly:

WGSL                          Bind group layout entry        Pipeline / bind group
@group(0) @binding(0)    ==   { binding: 0, ... }       (group index, binding number)
var<uniform> u: Uniforms      { visibility: VERTEX }     (stage that reads it)
                              { buffer: { type:"uniform" } }   resource kind

A mismatch in the binding number, the group index, the visibility stage, or the resource type fails pipeline or draw validation. The fragment target format MUST equal the render-pass attachment format. ALWAYS cross-check WGSL against the layout. Route to webgpu-syntax-bind-groups, webgpu-wgsl-memory-layout.

Pattern 4: ALWAYS choose buffer usage flags by resource role

MAP_READ combines ONLY with COPY_DST; MAP_WRITE combines ONLY with COPY_SRC. NEVER add STORAGE, UNIFORM, or VERTEX to a MAP_READ buffer; that fails validation. A storage buffer cannot be mapped, so GPU to CPU readback ALWAYS uses a separate MAP_READ | COPY_DST staging buffer fed by copyBufferToBuffer. Route to webgpu-syntax-buffers, webgpu-impl-buffer-upload.

Pattern 5: ALWAYS register device.lost and use error scopes as part of setup

Device-loss handling is part of a correct setup, not an afterthought. Register device.lost.then(...) in step 4, BEFORE any resource is created. During setup, wrap suspect resource creation in pushErrorScope("validation") / popErrorScope() to localize failures. Recovery means re-running steps 1 to 15 against a NEW device; resources are bound to the device that created them. NEVER write a silent retry loop. Route to webgpu-errors-device-loss, webgpu-errors-validation.

Pattern 6: ALWAYS label every object and run per-frame steps with a fresh encoder

Every descriptor accepts a label; GPUError messages quote it. Set a meaningful label on every buffer, texture, pipeline, bind group, shader module, and encoder. Command buffers are single-use: each frame creates a fresh GPUCommandEncoder (step 13). context.getCurrentTexture() is called once per frame and NEVER cached. Route to webgpu-errors-debugging, webgpu-syntax-canvas-context.

Skill Routing Map

For any step or question, route to the matching sibling skill. All 33 detailed skills:

Common Anti-Patterns

1. Creating buffers or textures before negotiating limits and features. Sizes planned without reading adapter.limits exceed device limits on lower-tier hardware and fail validation. Steps 1 to 3 ALWAYS precede step 11.

2. Building a pipeline before its bind group layouts exist. The pipeline consumes the pipeline layout, which consumes the bind group layouts. Step 8 ALWAYS precedes steps 9 and 10.

3. Mismatched @binding numbers across WGSL and the bind group layout. A WGSL @binding(2) with no { binding: 2 } layout entry, or a visibility stage that excludes the reading stage, fails pipeline or draw validation.

See references/anti-patterns.md for the full list with WHY-it-fails explanations.

Critical Warnings

• NEVER create a resource before steps 1 to 4 complete. The device must exist and limits must be negotiated first.
• NEVER call createRenderPipeline or createComputePipeline before its GPUBindGroupLayout objects exist.
• NEVER let WGSL @group / @binding numbers, the bind group layout binding numbers, the visibility stages, or the formats disagree. All must align exactly.
• NEVER add STORAGE, UNIFORM, or VERTEX usage to a MAP_READ buffer. MAP_READ combines ONLY with COPY_DST.
• NEVER skip device.lost registration. Register it in step 4, before any resource. See webgpu-errors-device-loss.
• NEVER ship descriptors without a label. Validation messages reference objects by label. See webgpu-errors-debugging.
• NEVER cache context.getCurrentTexture() or reuse a GPUCommandBuffer. Each frame needs a fresh texture and a fresh encoder.

Reference Files

• references/methods.md : the ordered setup checklist for the render and compute paths, the buffer-usage-flag table per resource role, and the full task-to-skill routing map.
• references/examples.md : a complete verified minimal render setup and a complete minimal compute setup, end to end.
• references/anti-patterns.md : orchestration-level mistakes (wrong setup order, missing steps) with WHY-it-fails explanations.

Related skills: this orchestrator routes to all 33 detailed WebGPU skills listed in the Skill Routing Map above. For deep API detail on any single step, open the routed skill.