Workflow schema declaration

In HUMΛN, workflows are AI capabilities — not orphaned DAG JSON. A humanos.workflow.v1 manifest declares steps, triggers, required capabilities, and provenance hooks so Builder, HumanOS, MCP, and Companion can invoke the same governed contract.

Overview

Surface	Purpose
POST /v1/builder/workflows	Create draft workflow + manifest
PUT /v1/builder/workflows/:id	Update manifest / lifecycle
POST /v1/builder/workflows/:id/publish	Publish after readiness checklist
GET /v1/workflows/:id/dag	Runtime DAG + stats (orchestration view)
POST /v1/builder/workflows/from-companion	Companion → builder handoff

Canon: kb/163_workflows_orchestration.md, kb/136, routes in apps/api/src/routes/builder/index.ts and apps/api/src/routes/workflows.ts.

Minimal manifest shape

const manifest = {
  kind: 'humanos.workflow.v1',
  id: 'acme.invoice-approval',
  name: 'Invoice approval pipeline',
  version: '1.0.0',
  publisher: 'did:org:acme',
  steps: [
    {
      id: 'extract',
      capability: 'human.documents.parse',
      inputs: { mime_type: 'application/pdf' },
    },
    {
      id: 'route',
      capability: 'humanos.route',
      inputs: { required_capabilities: ['accounting'] },
    },
    {
      id: 'approve',
      capability: 'humanos.approvals.wait',
      inputs: { queue: 'finance' },
    },
  ],
  triggers: [{ type: 'manual' }, { type: 'webhook', path: '/hooks/invoice' }],
};

Each step references a capability id resolvable in the Capability Graph — not ad-hoc function names.

Create and publish

Publish returns readiness warnings even on success — fix before marketplace linkage when scope: 'org'.

Intent → workflow handoff

Link builder workflows to Intent briefs for lineage:

// After client.intent.compile(briefId)
await client.raw.POST('/v1/builder/workflows', {
  body: {
    name: 'From shaped intent',
    manifest: compiledManifest,
    intent_brief_id: briefId,
  },
});

// Or direct Companion handoff
await client.raw.POST('/v1/builder/workflows/from-companion', {
  body: {
    companion_session_id: sessionId,
    proposed_manifest: manifest,
  },
});

GET /v1/intent/:id/lineage includes execution_runs tied to the brief.

Workflow handoff (alias: workflow-handoff)

Cross-surface handoff keeps one auditable execution tree when a workflow invokes another workflow or surfaces continue in Companion / Console.

Community links to /docs/patterns/workflows/workflow-handoff resolve here.

Parent → child DAG audit

When fetching a child workflow DAG, pass parent_run_id so provenance reconstructs the full tree:

human api GET "/v1/workflows/$CHILD_WORKFLOW_ID/dag?parent_run_id=$PARENT_RUN_ID"

Response may include parent_run_id — Canon: kb/22 §P6 (single auditable record).

Handoff patterns

From	To	Mechanism
Companion shaped intent	Builder draft	POST /v1/builder/workflows/from-companion
Intent brief	Workflow row	intent_brief_id on create
Running workflow	Child workflow	child execute with parent_run_id query
Builder publish	Marketplace asset	org-scoped publish note → marketplace install when asset exists
MCP / agents	Callable capability	workflow id + human.workflow.* tools after publish

Prefer this page (workflows/schema-declaration) in new links. Thin alias: workflow-handoff.

Use cases

• Every workflow is an AI capability — expose same manifest to MCP org mesh and internal agents.
• HITL steps — declare humanos.approvals.wait steps; pair with Async executions.
• Multi-agent orchestration — combine with Multi-Agent Workflow.

Security considerations

See also

• Workflow handoff (alias)
• Multi-Agent Workflow
• Intent modes
• Community: Every workflow is an AI capability
• Guide: Workflow builder