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

You ship a pipeline that scores signals and writes artifacts. Install day, the PM asks: “Where do I tune sources? Where do I Like a brief? Where does Legal approve the PRD?” If your answer is “check the repo,” you built a batch job — not a platform citizen.

In HUMΛN, a workflow declares its own Command Plane sections, Companion quick actions, and Workforce Cloud work-item renderers in one humanos.workflow.v1 manifest. Install reads the manifest and wires the surfaces.

Scroll-stopper: A pipeline without surfaces is a job. A workflow with a manifest is a product someone can operate.

So that builders ship operable systems — config, feedback, and human gates — without a second integration project after the agents work.

A workflow is more than a pipeline

In HUMΛN, a workflow 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 once. The platform reads the manifest on install and wires everything up.

The manifest structure

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: { /* Command 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. Start with the pipeline; add surfaces progressively.

Command Plane extension (`cp_extension`)

The cp_extension block declares nav sections in the Command Plane sidebar under your workflow’s name.

For Signals, four sections:

cp_extension: {
  nav_scope: 'org',
  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 — your workflow ships UI; the Command Plane hosts it in the dynamic extension shell.

What belongs in Command Plane? Configuration an admin sets once: entity lists, source allowlists, routing weights, delivery destinations, learning proposal review. Not the real-time activity feed — that’s Companion.

Cascade on uninstall: Registered nav sections are removed automatically. No cleanup code.

Companion module (`companion_module`)

Quick actions when viewing a signal or artifact
Panels for 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.battlecard_update',
      ],
    },
  ],
},

PRD drafts and integration assessments are Workforce-gated — they are not Companion panel kinds.

“I like this” end-to-end:

User sees an executive brief in Companion
Taps “Like this”
signals/capture.intent fires with intent: 'like'
Like Capture creates a signals.like_capture artifact and emits positive_feedback_signal
Learning Engine aggregates on the next run
Admin reviews the proposal in Command Plane → approves → weight updated

The loop is event → learning proposal → admin approve — not free-form tuning in a spreadsheet.

Workforce Cloud module (`workforce_module`)

Work item renderers — rich UI for each human approval gate.

workforce_module: {
  work_item_renderers: [
    {
      id: 'prd-review',
      label: 'Review PRD Draft',
      artifact_kinds: ['signals.prd_draft'],
      renderer_type: 'review_artifact',
      actions: [
        { id: 'approve', label: 'Approve for next step', effect: 'release_to_delivery' },
        { id: 'revise', label: 'Request revision', effect: 'create_revised_artifact' },
        { id: 'dismiss', label: 'Dismiss', effect: 'dismiss_with_feedback' },
      ],
      feedback_emit: true,
    },
    // … integration-review, compliance-review, watch-candidate (see Signals manifest)
  ],
},

Notice:

artifact_kinds is an array
renderer_type maps to a contract: approval_gate, review_artifact, guided_workflow (Signals PRD uses review_artifact)
feedback_emit: true records the reviewer’s decision as a feedback signal
Renderer id must match renderer_id in ctx.approval.request()

How work items appear

await ctx.approval.request({
  installation_id: workforceInstallationId,
  renderer_id: 'prd-review',
  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 Workforce Cloud work item. On action: lifecycle update, feedback event, delivery proceeds or suppresses.

Approval is non-blocking for the pipeline. ctx.approval.request() is fire-and-forget — executive briefs keep shipping while the PRD waits.

The learning contract

learning: {
  enabled: true,
  infer_from: [
    'verdict_signal',
    'routing_signal',
    'artifact_quality_signal',
    'positive_feedback_signal',
    'delivery_signal',
  ],
  may_adapt: [
    'template_preference',
    'role_relevance_weighting',
    'source_trust_weighting',
    'digest_timing',
    'watch_candidates',
  ],
  may_not_adapt: [
    'policy_boundaries',
    'allowed_destinations',
    'risk_thresholds',
    'compliance_restrictions',
    'data_handling_rules',
  ],
},

Hard invariant: preferences may adapt; policy must remain explicit. Learning cannot expand destinations, soften risk thresholds, or rewrite compliance handling.

Install experience, end to end

Bundle install iterates members
Workflow member: installation row + config layers from preset
Manifest registers Command Plane nav, Companion actions/panels, Workforce renderers
First scheduled scan may trigger immediately
Companion can receive the first artifact before the wizard closes

One manifest, one install call, full platform integration.

Designing Workforce renderers

Mistake: too many actions on one work item. Aim for ≤3 options.

Good: Approve / Request revision / Dismiss

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

Design for decisions, not option trees. Signals renderers are the reference for keeping it tight.

Go deeper

Product: Command Plane, Companion, Workforce
Docs: Building your first extension, Workforce concepts
Community: Building Signals, CLI scaffolding, Controlling execution lifecycle