AgentWorks

AgentWorks documentation

Workflow Manifest Architecture

Status

This migration is complete.

Workflow mode is now manifest-backed, and workflow.json is the source of truth for workflow definition.

Current reality:

The old migration-plan framing is obsolete.

Canonical File

Each workflow workspace has a top-level manifest:

The backend struct lives in workflow_manifest.go.

Current Manifest Shape

{
  "schema_version": 1,
  "id": "wf_ab12cd34",
  "label": "Customer onboarding",
  "objective": "Optional workflow-level objective",
  "success_criteria": "Optional workflow-level success criteria",
  "capabilities": {
    "selected_servers": ["github"],
    "selected_tools": [],
    "selected_skills": ["account-research"],
    "selected_secrets": ["my-secret-name"],
    "selected_global_secret_names": null,
    "browser_mode": "none",
    "use_code_execution_mode": false,
    "llm_config": {
      "schema_version": 2,
      "mode": "explicit",
      "builder_llm": {
        "provider": "openai",
        "model_id": "gpt-4.1"
      },
      "maintenance_llm": {
        "provider": "anthropic",
        "model_id": "claude-opus-4-8"
      },
      "pulse_llm": {
        "provider": "anthropic",
        "model_id": "claude-sonnet-5"
      },
      "tiered_config": {
        "tier_1": {
          "provider": "openai",
          "model_id": "gpt-4.1"
        },
        "tier_2": {
          "provider": "openai",
          "model_id": "gpt-4.1-mini"
        },
        "tier_3": {
          "provider": "openai",
          "model_id": "gpt-4.1-nano"
        }
      }
    }
  },
  "execution_defaults": {
    "always_use_same_run": false,
    "disable_learning": false,
    "global_skill_objective": "What the shared skill should capture",
    "disable_parallel_tool_execution": false,
    "execution_max_turns": 100,
    "enabled_custom_tools": ["workspace_advanced:*", "human_tools:*"]
  },
  "ownership": {
    "employee_id": null
  },
  "schedules": [
    {
      "id": "sched_123",
      "name": "Daily run",
      "cron_expression": "0 9 * * 1-5",
      "timezone": "Asia/Kolkata",
      "enabled": true,
      "group_ids": ["default"]
    }
  ],
  "created_at": "2026-04-09T10:00:00Z",
  "updated_at": "2026-04-09T10:00:00Z",
  "oversight_mode": "supervised",
  "decision_log_mutability": "append_only"
}

What Lives In The Manifest

capabilities

Workflow-wide execution defaults:

Notes:

execution_defaults

Workflow-level persistent execution defaults:

This is now the active home for global step overrides.

Runtime code reads global overrides from workflow.json.execution_defaults, not from planning/step_override.json.

ownership

Workflow assignment is manifest-backed now.

schedules

Schedules are manifest-backed now and no longer depend on DB workflow metadata.

Current schedule fields include:

For current runtime behavior, APIs, run history, and workshop-vs-workflow execution paths, see workflow_scheduling.md.

Auto-improvement framework fields

Two optional top-level fields configure hard behavioral gates the auto-improvement framework reads. All default to backward-compatible values; existing workflows can omit them.

Field Values Default Purpose
oversight_mode manual | supervised | autonomous supervised Controls when human approval is required for high-risk framework changes. Hard gate.
decision_log_mutability append_only | append_only_strict append_only append_only_strict forbids any edit to a structured improve.md decision entry, even corrective. Used by compliance workflows. Hard gate.

The workflow's profile — typology (deterministic / exploratory / contextual), plan stability, runtime mode (single / dual explore-exploit), and whether it accumulates business context — lives as prose in builder/improve.md under a ## Workflow Profile section. The agent reads improve.md on every improvement turn and adjusts behavior accordingly. Real workflows mix axes a single enum can't express (e.g. social-media is exploratory + dual-mode + accumulating-context all at once); prose captures the nuance, and the framework no longer hard-gates on a workflow_type value.

For the design rationale and worked examples, see auto_improvement_framework.md.

What Does Not Belong In The Manifest

Do not store live runtime/session state in workflow.json:

Do not store secret values:

Other Workflow Files

The manifest does not replace the rest of the workspace.

These still live alongside it:

workflow.json is the workflow-level definition file. The planning files are still the step graph and execution-plan files.

Runtime Flow

Discovery

Backend discovery uses DiscoverWorkflowManifests, which scans workspace folders and reads workflow.json.

CRUD APIs

Manifest routes are registered in server.go:

Execution bootstrap

Workflow execution loads manifest capabilities before running:

Workshop phase sessions also load manifest config directly:

Scheduling

The scheduler is manifest-based:

It scans workflow manifests, loads enabled schedules, and executes them without DB workflow dependency.

Frontend state

The frontend has a dedicated manifest store:

The old "workflow preset" view is now a compatibility layer built from manifests:

Current Compatibility Leftovers

A few migration-era leftovers still exist in code, but they are no longer the architecture:

These are compatibility remnants, not the main design.

Key Files