Workflows as Platform Extensions: Control Plane, Companion, and Workforce Cloud

A workflow is more than a pipeline

When most people think about AI workflows, they think about a sequence of steps. Kick off a run, get outputs. That's half the picture.

In HUMΛN, a workflow is a platform citizen. It can:

Declare its own section in the Command Plane (configuration UI, dashboard, learning proposals)
Register quick actions in the Companion (Like this, Flag this, Watch source)
Define work item renderers in Workforce Cloud (rich review screens for human approval gates)

All of this is declared in a single humanos.workflow.v1 manifest. The platform reads the manifest on install and wires everything up automatically.

The manifest structure

Here's the top-level structure of a workflow manifest:

import type { WorkflowManifestV1 } from '@human/platform-extensions';

const manifest: WorkflowManifestV1 = {
  kind: 'humanos.workflow.v1',
  id: 'my-workflow',
  name: 'My Workflow',
  display_name: 'My Workflow — What It Does',
  version: '1.0.0',
  description: '...',
  triggers: [ /* schedule, event, manual_capture */ ],
  steps: [ /* agent invocations with depends_on */ ],
  workers: { /* swappable sub-agent bindings */ },
  cp_extension: { /* Control Plane surfaces */ },
  companion_module: { /* Companion quick actions + panels */ },
  workforce_module: { /* Workforce Cloud work item renderers */ },
  learning: { /* what can adapt vs. what is fixed */ },
  policy_hooks: [ /* pre-route and pre-release policy checks */ ],
};

Each block is optional. You can start with just the workflow pipeline and add surfaces progressively.

Control Plane extension (`cp_extension`)

The cp_extension block declares nav sections that appear in the Control Plane sidebar under your workflow's name.

For Signals, we declare four sections:

cp_extension: {
  nav_scope: 'org',       // appears in org-level CP navigation
  sections: [
    {
      id: 'signals-overview',
      label: 'Signals',
      icon: 'pulse',
      type: 'nav_section',
      route: '/extensions/signals/overview',
      component_url: '/extensions/signals/overview/index.js',
    },
    {
      id: 'signals-entities',
      label: 'Entities & Sources',
      icon: 'telescope',
      type: 'nav_section',
      route: '/extensions/signals/entities',
      component_url: '/extensions/signals/entities/index.js',
    },
    {
      id: 'signals-config',
      label: 'Configuration',
      icon: 'sliders',
      type: 'nav_section',
      route: '/extensions/signals/config',
      component_url: '/extensions/signals/config/index.js',
    },
    {
      id: 'signals-learning',
      label: 'Learning Proposals',
      icon: 'brain',
      type: 'nav_section',
      route: '/extensions/signals/learning',
      component_url: '/extensions/signals/learning/index.js',
    },
  ],
},

Each section loads a remote component via component_url. This is a micro-frontend architecture — your workflow ships its own UI, and the Control Plane hosts it in the dynamic extension shell.

What belongs in CP? Configuration that an admin sets up once. Entity lists, source allowlists, routing weights, delivery destinations, learning proposal review. Not the real-time activity feed — that's the Companion.

Cascade on uninstall: When an org uninstalls Signals, all registered CP nav sections are removed automatically. The platform handles this via the manifest — no cleanup code needed.

Companion module (`companion_module`)

The Companion module wires up two things:

Quick actions that appear when viewing a signal or artifact
Panels that show a persistent queue of incoming artifacts

companion_module: {
  quick_actions: [
    {
      id: 'like',
      label: 'Like this',
      icon: 'thumbs-up',
      event: 'signals/capture.intent',
      payload: { intent: 'like' },
    },
    {
      id: 'flag',
      label: 'Flag',
      icon: 'flag',
      event: 'signals/capture.intent',
      payload: { intent: 'flag' },
    },
    {
      id: 'dismiss',
      label: 'Dismiss',
      icon: 'x',
      event: 'signals/capture.intent',
      payload: { intent: 'dismiss' },
    },
    {
      id: 'watch',
      label: 'Watch source',
      icon: 'eye',
      event: 'signals/capture.intent',
      payload: { intent: 'watch' },
    },
  ],
  panels: [
    {
      id: 'signals-queue',
      title: 'Signals Queue',
      empty_state: 'No new signals today',
      artifact_kinds: [
        'signals.executive_brief',
        'signals.product_gap_memo',
        'signals.content_brief',
        'signals.prd_draft',
        'signals.integration_assessment',
        'signals.battlecard_update',
      ],
    },
  ],
},

Every quick action emits a typed event (signals/capture.intent) that the Like Capture agent processes.

This is how "I like this" works end-to-end:

User sees an executive brief in their Companion queue
Taps "Like this"
signals/capture.intent event fires with intent: 'like'
Like Capture agent creates a signals.like_capture artifact and emits positive_feedback_signal
Learning Engine aggregates this in the next run
After enough positive signals, the learning engine proposes boosting this signal type's confidence
Admin reviews the proposal in CP → approves → confidence weight updated

No manual tuning. Just tap.

Workforce Cloud module (`workforce_module`)

This is where things get powerful. The workforce_module block declares work item renderers — rich UI components for each human approval gate in your workflow.

For Signals, we have five renderers:

workforce_module: {
  work_item_renderers: [
    {
      id: 'signal-review',
      label: 'Review Signal',
      artifact_kinds: ['signals.executive_brief', 'signals.product_gap_memo'],
      renderer_type: 'approval_gate',
      actions: [
        { id: 'approve', label: 'Approve for delivery', effect: 'release_to_delivery' },
        { id: 'reject', label: 'Reject', effect: 'dismiss_with_feedback' },
        { id: 'escalate', label: 'Escalate', effect: 'escalate_to_admin' },
      ],
      feedback_emit: true,
    },
    {
      id: 'prd-review',
      label: 'Review PRD Draft',
      artifact_kinds: ['signals.prd_draft'],    // array, not single string
      renderer_type: 'edit_artifact',
      actions: [
        { id: 'approve', label: 'Approve', effect: 'release_to_delivery' },
        { id: 'revise', label: 'Request revision', effect: 'create_revised_artifact' },
        { id: 'dismiss', label: 'Dismiss', effect: 'dismiss_with_feedback' },
      ],
      feedback_emit: true,
    },
    {
      id: 'integration-review',
      label: 'Review Integration Assessment',
      artifact_kinds: ['signals.integration_assessment'],
      renderer_type: 'review_artifact',
      actions: [
        { id: 'approve', label: 'Approve', effect: 'release_to_delivery' },
        { id: 'revise', label: 'Request revision', effect: 'create_revised_artifact' },
        { id: 'dismiss', label: 'Dismiss', effect: 'dismiss_with_feedback' },
      ],
      feedback_emit: true,
    },
    {
      id: 'compliance-review',
      label: 'Compliance Acknowledgment',
      artifact_kinds: ['signals.compliance_review'],
      renderer_type: 'guided_workflow',
      actions: [
        { id: 'acknowledge', label: 'Acknowledge & Release', effect: 'release_to_delivery' },
        { id: 'suppress', label: 'Suppress Signal', effect: 'dismiss_with_feedback' },
        { id: 'escalate', label: 'Escalate to Legal', effect: 'escalate_to_admin' },
      ],
      feedback_emit: true,
    },
    {
      id: 'watch-candidate',
      label: 'Review Watch Candidate',
      artifact_kinds: ['signals.watch_candidate'],
      renderer_type: 'approval_gate',
      actions: [
        { id: 'approve', label: 'Add to watched sources', effect: 'release_to_delivery' },
        { id: 'reject', label: 'Reject', effect: 'dismiss_with_feedback' },
        { id: 'defer', label: 'Defer', effect: 'defer_to_next_run' },
      ],
      feedback_emit: true,
    },
  ],
},

Key things to notice:

artifact_kinds is an array — one renderer can handle multiple artifact types
renderer_type maps to a rendering contract: approval_gate, review_artifact, edit_artifact, guided_workflow
feedback_emit: true means the platform automatically records the reviewer's decision as a feedback signal
The id in the renderer declaration must match the renderer_id in ctx.approval.request() calls

How work items appear in Workforce Cloud

When artifact-workers.ts calls ctx.approval.request():

await ctx.approval.request({
  installation_id: workforceInstallationId,
  renderer_id: 'prd-review',         // ← must match workforce_module renderer id
  artifact_id: artifact.artifact_id,
  urgency: signalUrgencyToApprovalUrgency(signal.urgency),
  metadata: {
    entity: signal.entity_name,
    event_type: signal.signal_type,
    signal_confidence: signal.confidence,
    workflow_run_id: input.workflow_run_id,
  },
});

The platform creates a work item in the reviewer's Workforce Cloud queue, rendered using the prd-review renderer component. The reviewer sees the full PRD draft, the source signal, the confidence score, and the three actions. When they select an action, the platform:

Updates the artifact's lifecycle state
Records the decision as a feedback event
Notifies the delivery orchestrator to proceed (or suppress)

Approval is non-blocking for the pipeline. The ctx.approval.request() call is fire-and-forget — the orchestrator continues delivering other artifacts. The PRD draft sits in Workforce Cloud until approved, without holding up executive briefs or gap memos.

The learning contract

The learning block in the manifest declares exactly what the platform is allowed to adapt — and what it must never touch:

learning: {
  enabled: true,
  infer_from: [
    'verdict_signal',
    'routing_signal',
    'artifact_quality_signal',
    'positive_feedback_signal',
    'delivery_signal',
  ],
  may_adapt: [
    'template_preference',      // ← platform can learn preferred brief style
    'role_relevance_weighting', // ← routing weights can drift toward observed patterns
    'source_trust_weighting',   // ← sources with high approval rates get higher trust
    'digest_timing',            // ← delivery cadence adapts to engagement
    'watch_candidates',         // ← suggested new sources after repeated captures
  ],
  may_not_adapt: [
    'policy_boundaries',        // ← never. policy is admin-set, not learned.
    'allowed_destinations',     // ← delivery destinations don't auto-expand
    'risk_thresholds',          // ← compliance thresholds stay explicit
    'compliance_restrictions',
    'data_handling_rules',
  ],
},

The hard invariant: preferences may adapt; policy must remain explicit. No matter how many signals flow through, the learning system cannot change what destinations are permitted, what risk thresholds trigger review, or how compliance signals are handled. Those stay under admin control.

The install experience, end to end

When an org installs the Signals bundle:

install-bundle.ts iterates all bundle members
For each workflow member: creates a marketplace_installation row, seeds humanos_workflow_config_layers with package-default config from the install preset
The manifest is read: CP nav sections registered, Companion quick actions registered, Companion panels registered, Workforce renderers registered
The first scheduled scan is triggered immediately (if trigger_first_run: true in the preset)
Companion receives the first artifact before the install wizard closes

From the builder's perspective: one manifest, one install call, full platform integration.

Designing your own workforce renderers

The most common mistake when designing Workforce Cloud renderers is putting too many actions on a single work item. A reviewer should almost never need to choose between more than 3 options.

Good: Approve / Request revision / Dismiss

Bad: Approve / Approve with caveats / Send to another reviewer / Request more data / Escalate / Dismiss / Archive / Mark urgent

The platform enforces no limit, but users will ignore complex work items. Design for decisions, not options. The Signals renderers are the reference for keeping it tight.

What's next

The third article shows the CLI scaffolding that generates all of this boilerplate — and the SDK testing helpers that let you verify every escalation path without a live Workforce Cloud instance.

Questions? Join the discussion → community.builtwithhuman.com